altertable-ai/altertable-swift

Capture user behavior and product events in Swift apps with Altertable

Installation

Add altertable-swift as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/altertable-ai/altertable-swift.git", from: "0.1.0")
]

Quick Start

import Altertable

// Initialize
let client = Altertable(apiKey: "your-api-key")

// Track an event
client.track(event: "Button Clicked", properties: ["button_id": "signup"])

Examples

Check out the Examples directory for a complete runnable mini-app.

Signup Funnel (SwiftUI)

A complete 4-step signup funnel matching our web example journey:

Personal Info: Screen view tracked via .screenView(name: "Personal Info")
Account Setup: Screen view tracked via .screenView(name: "Account Setup")
Choose Plan: Screen view tracked via .screenView(name: "Plan Selection") and track("Plan Selected")
Completion: Screen view tracked via .screenView(name: "Welcome"), identify(userId, traits), and track("Form Submitted")

API Reference

`track(event:properties:)`

Records an event with optional properties.

client.track(event: "Purchase", properties: ["amount": 29.99])

`identify(userId:traits:)`

Identifies a user with a unique ID and optional traits.

client.identify(userId: "user_123", traits: ["plan": "pro"])

`alias(newUserId:)`

Links a new ID to the current user (e.g. after sign up).

client.alias(newUserId: "user_456")

`updateTraits(_ traits:)`

Updates traits for the currently identified user.

client.updateTraits(["email": "new@example.com"])

`reset()`

Clears the current session and identity (e.g. on logout).

client.reset()

`flush(completion:)`

Forces buffered events to be sent as soon as possible. The optional completion runs on the SDK’s serial queue once the buffer is empty and any in-flight batches from this flush have finished (or failed without being re-queued).

client.flush()
client.flush {
    // flush finished
}

`configure(_:)`

Updates the configuration after initialization. Use a closure to modify configuration properties in place.

client.configure { config in
    config.trackingConsent = .granted
    config.environment = "staging"
    config.debug = true
}

Note: requestTimeout, flushOnBackground, flushEventThreshold, flushIntervalMs, and maxBatchSize are init-only properties. Changes to these via configure() are ignored.

`screen(name:properties:)`

Tracks a screen view with optional properties.

client.screen(name: "HomeScreen", properties: ["section": "main"])

Screen Views

The SDK provides multiple ways to track screen views, with platform-specific capabilities:

screen(name:properties:): Works on all platforms that run Swift
UIKit auto-capture: Available on UIKit platforms (iOS, tvOS) when captureScreenViews is enabled
SwiftUI .screenView() modifier: Available on platforms that support SwiftUI

Cross-Platform Manual Tracking

The screen() method works on all platforms:

client.screen(name: "HomeScreen", properties: ["section": "main"])

UIKit Auto-Capture (iOS, tvOS only)

On UIKit platforms, screen views can be automatically tracked when view controllers appear. The SDK extracts screen names by removing the ViewController suffix from the class name (e.g., HomeViewController → Home).

// Automatically tracks "Home" when HomeViewController appears
class HomeViewController: UIViewController { }

Auto-capture is enabled by default. To disable:

let config = AltertableConfig(captureScreenViews: false)
let client = Altertable(apiKey: "your-api-key", config: config)

Note: Auto-capture is only available on UIKit platforms. On other platforms (macOS, Linux, watchOS), captureScreenViews has no effect and you should use manual tracking.

SwiftUI (Platforms with SwiftUI support)

Inject the client once at the app level, then use .screenView() anywhere in the view hierarchy with no extra wiring:

import SwiftUI
import Altertable

@main
struct MyApp: App {
    let analytics = Altertable(apiKey: "your-api-key")

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.altertable, analytics)
        }
    }
}

struct HomeView: View {
    var body: some View {
        Text("Welcome")
            .screenView(name: "Home")
    }
}

The client is resolved in order: explicit client parameter → \.altertable environment value → shared integration fallback. For most apps, the environment approach covers everything.

Configuration

Initialize with an AltertableConfig object for advanced options.

Event batching

Events are buffered and sent in HTTP batches (JSON arrays) instead of one request per event. Flushes happen when the buffer hits flushEventThreshold, on each flushIntervalMs tick while consent is granted, when you call flush(), and when the app backgrounds (if flushOnBackground is true). Failed deliveries that are retryable (e.g. network errors, 5xx, 429) can be re-queued after HTTP-level retries are exhausted.

License

MIT

Package Metadata

Repository: altertable-ai/altertable-swift

Homepage: https://altertable.ai

Stars: 1

Forks: 1

Open issues: 0

Default branch: main

Primary language: swift

License: MIT

README: README.md