0.1.0 (2026-03-10)

Initial release of the official Swift SDK for Altertable Product Analytics! 🚀

Added

Core Analytics: Complete SDK implementation supporting track(), identify(), alias(), updateTraits(), and screen() events.
SwiftUI Integration: Seamless .screenView(name:) modifier to easily track screens in the view hierarchy via @Environment.
UIKit Auto-Capture: Automatically tracks screen views on iOS and tvOS when ViewControllers appear.
Storage & Transport: Robust event queue with background flushing, batching, retry logic, and offline support.
Tracking Consent: Built-in management for tracking consent states.
Full Configuration: Setup your project with customizable options for environments, debug logging, and queue limits.

Altertable Swift SDK

The official Swift SDK for Altertable Product Analytics.

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()`

Forces any queued events to be sent immediately.

client.flush()

`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 and flushOnBackground 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.

Option	Type	Default	Description
`apiKey`	`String`	(Required)	Your project API key.
`baseURL`	`URL`	`https://api.altertable.ai`	The API endpoint URL.
`environment`	`String`	`production`	Environment name (e.g. `staging`).
`trackingConsent`	`TrackingConsentState`	`.granted`	Controls if tracking is enabled.
`debug`	`Bool`	`false`	Enables verbose logging.
`requestTimeout`	`TimeInterval`	`10.0`	Network request timeout in seconds.
`flushOnBackground`	`Bool`	`true`	Automatically flush events when app backgrounds.
`captureScreenViews`	`Bool`	`true`	Automatically track screen views on UIKit platforms (iOS, tvOS). On other platforms, use `screen()` or `.screenView()` for manual tracking.

License

MIT