AirLeg Guide

Quick Start

Initialize SDK

Call AirLeg.start(with:) from the application's startup lifecycle. For UIKit apps, the most direct integration point is application(_:didFinishLaunchingWithOptions:) in AppDelegate.

Use the builder to assemble the configuration first, then start the SDK at the top of the app lifecycle entry point.

import UIKit
import AirLeg

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        let configuration = AirLeg.ConfigurationBuilder(apiKey: "demo-key")
            .environment(.production(baseURL: URL(string: "https://api.example.com")!))
            .privacyMode(.full)
            .autoStartTracking(true)
            .autoRequestTrackingAuthorization(false)
            .build()

        AirLeg.start(with: configuration)
        return true
    }
}

SwiftUI apps can use the same builder in the App initializer before rendering the first scene. The full lifecycle examples live in Docs/INTEGRATION.md.

Installation

Choose the distribution path that matches your project

AirLeg supports multiple install surfaces and tracks verification status for each one.

Install AirLeg using the method that best fits your current project setup. For example, Swift Package Manager works well for Swift-first apps, while CocoaPods and manual XCFramework integration are useful for projects with existing dependency or build constraints.

Method	Status	How to use it
Swift Package Manager	Supported	`.package(url: "https://github.com/leejh08/AirLeg.git", exact: "0.1.0")`
CocoaPods	Supported	`pod 'AirLeg', :git => 'https://github.com/leejh08/AirLeg.git', :tag => '0.1.0'`
Tuist	Supported	`.remote(...)` + `.package(product: "AirLeg")`
Manual XCFramework	Supported	`./scripts/build-xcframework.sh` + `Embed & Sign` in Xcode

SDK Guides

Event Tracking

AirLeg supports typed standard events and flexible custom events.

Use standard events when the event semantics are already well known and should remain consistent across apps. Use custom events when the event is domain-specific and best defined by the integrating app.

Standard events

Standard events are modeled as typed APIs so event names and required attributes stay consistent at compile time.

screenView(name:)
signUp(method:)
login(method:)
addToCart(productID:price:currency:)
purchase(orderID:price:currency:)

AirLeg.track(.screenView(name: "Home"))
AirLeg.track(.purchase(
  orderID: "order_123",
  price: "29.99",
  currency: "USD"
))

Custom events

Use custom(name:attributes:) when the event is specific to your app or domain and does not fit the built-in standard event taxonomy.

AirLeg.track(.custom(
  name: "sample_custom",
  attributes: [
    "campaign": "spring",
    "source": "sample-app"
  ]
))

SDK Guides

User Identity

Attach user-level context while keeping privacy filtering rules centralized in the SDK.

Identity APIs are optional. Use them when the app has a meaningful user concept and you want tracked events to carry user context. Clear the identity when the active account changes or the user signs out.

Identity APIs

setUserID(_:)
setUserEmail(_:)
setUserPhone(_:)
setUserAttributes(_:)
clearUser()

AirLeg.setUserID("user_123")
AirLeg.setUserEmail("[email protected]")
AirLeg.setUserAttributes([
  "plan": "pro",
  "region": "kr"
])

Design intent

User state stays inside the SDK runtime and is filtered according to the active privacy mode before it is exposed in debug state or payloads. This keeps privacy behavior centralized instead of pushing that burden to every call site.

AirLeg.clearUser()

SDK Guides

Privacy & Tracking Control

AirLeg models data collection rules explicitly instead of treating them as UI-only preferences.

Privacy and tracking options are runtime behavior controls. They change whether events may be queued, whether sensitive fields are filtered, and whether tracking starts immediately after initialization.

`full`

Normal collection mode with standard event queueing behavior.

.privacyMode(.full)

`restricted`

Tracking starts paused and sensitive fields like email and phone are filtered from both identity state and queued event payloads.

.privacyMode(.restricted)
AirLeg.startTracking()

`consentRequired`

Queueing is blocked until consent is granted via setConsent(true), so event collection can stay aligned with app-level consent flows.

.privacyMode(.consentRequired)
AirLeg.setConsent(true)

SDK Guides

Delivery

The delivery pipeline combines queueing, retry policy, typed errors, and optional request signing.

Delivery covers what happens after an event is tracked: queue storage, flush timing, retry behavior, and transport integrity. This is where reliability and failure handling matter most for SDK consumers.

Runtime behavior

AirLeg keeps events in a queue first and only removes them after successful delivery.

In-memory queue by default
Persistent queue when queuePersistenceURL is set
Retry-aware flush()
Typed delivery errors through AirLegError

try await AirLeg.flush()

Builder options

Use builder options to tailor delivery behavior without changing the public tracking API shape.

retryPolicy(_:)
signatureSecret(_:)
autoStartTracking(_:)
queuePersistenceURL(_:)
session(_:)

let config = AirLeg.ConfigurationBuilder(apiKey: "demo-key")
  .retryPolicy(.init(retryDelaysInNanoseconds: [0, 10_000_000]))
  .signatureSecret("airleg-secret")
  .autoStartTracking(true)
  .build()

SDK Guides

Deep Link & Deferred Deep Link

Immediate and deferred routes are normalized into the same route model.

Use immediate deep link handling when the app already opened with a URL or universal link. Use deferred deep link resolution when the SDK should ask a backend for a route that was stored before the app was opened.

Immediate routes

Custom scheme and universal links are normalized through AirLeg.Route, route(for:), handle(_:), and observeRoutes(_:).

if let route = AirLeg.route(for: url) {
  print(route.path)
}

Deferred routes

resolveDeferredDeepLink() fetches a server-provided deferred URL and restores it as the same route type. This keeps immediate and deferred navigation flows aligned in the SDK interface.

let route = try await AirLeg.resolveDeferredDeepLink()
print(route?.path as Any)

SDK Guides

App Tracking Transparency

AirLeg provides a minimal ATT-aware surface so apps can inspect and request tracking authorization without hard-coding Apple framework calls everywhere.

ATT support in AirLeg is intentionally lightweight. It gives the app a consistent SDK-facing status model and request helper, while still letting the app decide when the ATT prompt should be shown.

Status and request APIs

Use the SDK to read the current authorization state and request permission when appropriate.

let status = AirLeg.trackingAuthorizationStatus()
let updated = await AirLeg.requestTrackingAuthorization()

Builder options

Use configuration to express whether the SDK should auto-request tracking authorization and what timeout policy should be associated with that flow.

let configuration = AirLeg.ConfigurationBuilder(apiKey: "demo-key")
  .autoRequestTrackingAuthorization(false)
  .build()

Related Docs

Reference documents

Use these docs for deeper architecture, integration, verification, and delivery details.

Installation Guide SPM, CocoaPods, Tuist, and manual XCFramework setup Integration Guide UIKit / SwiftUI integration and runtime usage Architecture Runtime boundaries, delivery, privacy, and verification layers Plan Milestones, phases, and current SDK development status CI/CD GitHub Actions workflows and release verification policy Install Verification Matrix Current verification status for each distribution path