AirLeg

AirLeg is a portfolio-grade B2B-style iOS SDK for event collection, delivery reliability, deep link routing, deferred deep link simulation, and privacy-aware client behavior.

Current product scope

AirLeg currently focuses on the SDK product surface itself:

• typed standard and custom event tracking
• user identity state
• privacy and tracking control
• in-memory and persistent queueing
• batch flush with retry-aware delivery
• deep link route parsing
• deferred deep link resolution
• request signature generation

Development tooling such as the fake ingestion server, local dashboard, sample app, and validation scripts support SDK development and verification, but they are not part of the product feature surface.

Development approach

AirLeg development explicitly follows two complementary engineering practices:

• Test-Driven Development (TDD) — new SDK behavior is introduced through failing tests first, then implemented with the smallest code change that makes the test pass.
• Tidy First — structural cleanup and behavioral changes are kept separate so refactoring stays reviewable and does not hide feature changes.

In practice, this means the repository favors small red/green/refactor steps, behavior-oriented test names, and commit history that makes cleanup work distinguishable from product behavior changes.

What AirLeg does

AirLeg helps app teams handle a common set of mobile infrastructure concerns through one reusable SDK:

• track typed user events
• attach user identity context
• queue events offline and restore them after restart
• batch and retry network delivery
• normalize custom scheme and universal link handling
• resolve deferred deep links from a server response
• change collection and delivery behavior based on privacy mode
• sign outbound requests for stronger integrity guarantees

Current public API highlights

let configuration = AirLeg.ConfigurationBuilder(apiKey: "demo-key")
    .environment(.production(baseURL: URL(string: "https://api.example.com")!))
    .privacyMode(.full)
    .build()

AirLeg.start(with: configuration)
AirLeg.setUserID("user_123")
AirLeg.track(.purchase(orderID: "order_123", price: "29.99", currency: "USD"))
try await AirLeg.flush()

Additional public APIs currently available:

• AirLeg.setConsent(_:)
• AirLeg.startTracking() / AirLeg.stopTracking()
• AirLeg.setUserEmail(_:)
• AirLeg.setUserPhone(_:)
• AirLeg.setUserAttributes(_:)
• AirLeg.clearUser()
• AirLeg.handle(_:, onRoute:)
• AirLeg.route(for:)
• AirLeg.observeRoutes(_:)
• AirLeg.resolveDeferredDeepLink()
• AirLeg.debugSnapshot()
• AirLeg.trackingAuthorizationStatus()
• AirLeg.requestTrackingAuthorization()
• AirLeg.ConfigurationBuilder(...)

Supported events

Standard events

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

Custom events

• custom(name:attributes:)

Privacy and tracking behavior

AirLeg supports these modes:

• full
• restricted
• consentRequired

Current behavior includes:

• consentRequired blocks queueing before consent is granted
• restricted starts with tracking paused
• restricted filters sensitive fields such as email and phone from user identity and queued payloads
• explicit startTracking() / stopTracking() control

Delivery behavior

• in-memory queue by default
• file-backed persistent queue when queuePersistenceURL is configured
• retry-aware batch flush for transient failures
• queue is drained only after successful delivery

Deep linking

• custom scheme parsing
• universal link parsing
• route callback and observer support
• last handled route exposed in debug snapshot
• deferred deep link resolution from server response

Installation

AirLeg currently supports Swift Package Manager, CocoaPods via the repo podspec, Tuist package integration, and manual XCFramework generation.

Swift Package Manager

.package(url: "https://github.com/leejh08/AirLeg.git", exact: "0.1.0")

CocoaPods

pod 'AirLeg', :git => 'https://github.com/leejh08/AirLeg.git', :tag => '0.1.0'

Tuist

.remote(url: "https://github.com/leejh08/AirLeg.git", requirement: .exact("0.1.0"))

Then depend on .package(product: "AirLeg") from the target.

Manual install

./scripts/build-xcframework.sh

This generates Build/AirLeg.xcframework for local drag-and-drop integration. Add it to the app target's Frameworks, Libraries, and Embedded Content section as Embed & Sign so the dynamic framework is available at runtime.

Sample apps

• Apps/AirLegSampleApp — monorepo test application with shared verification utilities
• AirLegSwiftUISampleApp — SwiftUI integration and manual verification flow
• AirLegUIKitSampleApp — UIKit/AppDelegate integration and manual verification flow

Verification status

Current verification coverage includes:

• unit tests for event serialization, privacy, tracking control, request signing, queue behavior, deep link parsing, and deferred deep link logic
• integration tests for fake ingestion server endpoints, dashboard, failure injection, and deferred deep link server flow
• sample app integration test through AirLegSampleApp
• install-path verification tracking in Docs/INSTALL-VERIFICATION-MATRIX.md

Docs site

• Deployed guide: https://airleg-guide.dsmhs.kr
• Local entry point: site/index.html

Open the local file in a browser for a help-center-style overview of installation, SDK guides, and architecture.

Project documents

• Docs/HARNESS.md — harness design and verification tooling overview
• Docs/INSTALLATION.md — installation paths for SPM, CocoaPods, Tuist, and manual XCFramework builds
• Docs/INSTALL-VERIFICATION-MATRIX.md — install path support and verification status by distribution method
• Docs/ARCHITECTURE.md — internal SDK architecture and subsystem boundaries
• Docs/DOCS-SITE-IA.md — information architecture for the developer docs site
• Docs/INTEGRATION.md — UIKit / SwiftUI integration and verification flow
• Docs/CI-CD.md — GitHub Actions workflow structure and release verification policy
• Docs/PLAN.md — milestones, phases, and current SDK development checklist
• Docs/MANUAL-VERIFICATION.md — feature-by-feature manual verification flow for the sample apps
• backlog.md — now / next / later prioritization for the active SDK roadmap
• CHANGELOG.md — release notes by version

Non-goals

• full mobile attribution platform behavior
• ad partner integrations
• MMP feature parity
• large production backend infrastructure

Current status

Active SDK product development with local verification infrastructure.