Tell Swift SDK

Swift SDK for Tell — product analytics and structured logging for Apple platforms.

• Fire & forget. Synchronous API, async background worker. No await needed.
• Automatic sessions. Device ID, session management, anonymous-to-identified merging.
• Structured logging. RFC 5424 severity levels with service tags and structured data.
• Type-safe. Strongly typed events, properties, and currencies.

Installation

// Package.swift
dependencies: [
    .package(url: "https://github.com/tell-rs/sdk-swift.git", from: "1.0.0")
]

Or in Xcode: File > Add Package Dependencies > https://github.com/tell-rs/sdk-swift.git

Quick Start

import Tell

// Configure once at app startup — fire and forget
Tell.shared.configureAsync(apiKey: "feed1e11feed1e11feed1e11feed1e11")

// Track events
Tell.shared.track(.pageViewed, properties: [
    "url": "/home",
    "referrer": "google"
])

// Identify users
Tell.shared.identify("user_123", traits: [
    "name": "Jane",
    "plan": "pro"
])

// Revenue
Tell.shared.revenue(
    amount: 49.99,
    currency: .usd,
    orderID: "order_456",
    properties: ["product": "annual_plan"]
)

// Structured logging
Tell.shared.logError("Payment failed", service: "billing", data: [
    "error": "card_declined",
    "amount": 9.99
])

// Graceful shutdown
try await Tell.shared.close()

Configuration

// Presets — one-liner setup
Tell.shared.configure(apiKey: "feed1e11feed1e11feed1e11feed1e11", preset: .production)
Tell.shared.configure(apiKey: "feed1e11feed1e11feed1e11feed1e11", preset: .development)

// Custom — fire-and-forget, returns immediately
Tell.shared.configureAsync(
    apiKey: "feed1e11feed1e11feed1e11feed1e11",
    service: "my-ios-app",              // stamped on every event and log (auto-detected from bundle if omitted)
    endpoint: "collect.tell.rs:50000",  // default
    batchSize: 100,                     // events per batch
    flushInterval: 10,                  // seconds between flushes
    logLevel: .debug                    // SDK log level
)

// Async with error handling — blocks until connected
try await Tell.shared.configure(
    apiKey: "feed1e11feed1e11feed1e11feed1e11",
    onError: { error in print("Tell: \(error)") }
)

// See examples/config for all options

API

// Events
Tell.shared.track(eventName, properties: [...])
Tell.shared.identify(userId, traits: [...])
Tell.shared.group(groupId, properties: [...])
Tell.shared.revenue(amount:, currency:, orderID:, properties: [...])
Tell.shared.alias(previousId, userId: newId)

// Super properties — merged into every track/group/revenue call
Tell.shared.register(["app_version": "2.0"])
Tell.shared.unregister("app_version")

// Logging
Tell.shared.log(level, message, service:, data: [...])
Tell.shared.logInfo(message, service:, data: [...])
Tell.shared.logError(message, service:, data: [...])
// + logEmergency, logAlert, logCritical, logWarning,
//   logNotice, logDebug, logTrace

// Privacy
Tell.shared.optOut()    // events dropped locally
Tell.shared.optIn()
Tell.shared.isOptedOut()

// Lifecycle
Tell.shared.reset()              // logout — new anonymous ID
try await Tell.shared.flush()    // force send
try await Tell.shared.close()    // graceful shutdown

Log levels follow RFC 5424: .emergency, .alert, .critical, .error, .warning, .notice, .info, .debug, .trace.

Examples

The examples/ directory contains runnable sample applications:

• examples/events/ — Track events, identify users, revenue, groups
• examples/logging/ — Structured logging with all severity levels
• examples/config/ — Configuration options and patterns
• examples/e2e/ — End-to-end smoke test against a real collector
• examples/privacy/ — Opt-out / opt-in controls

swift run --package-path examples/events
TELL_ENDPOINT=collect.tell.rs:50000 swift run --package-path examples/e2e

Requirements

• iOS 16.0+ / macOS 13.0+ / visionOS 1.0+
• Swift 6.0+
• Xcode 16.0+

License

MIT