iOS SDK

ReflectSDK for native iOS — a Swift facade over the shared ReflectCore engine, consumable from Swift and Objective-C. This is the native SDK for a UIKit or SwiftUI app; if you ship through Flutter, React Native or Unity, use that wrapper instead.

Installation (CocoaPods)

Both pod lines below are required. Neither ReflectSDK nor the shared ReflectCore engine is published on CocoaPods trunk — both are consumed from their GitHub tags — and CocoaPods does not follow a git-sourced pod's dependency to another git source. Declaring only ReflectSDK fails with"None of your spec sources contain a spec satisfying the dependency: ReflectCore (~> 1.1)".

# Podfile
platform :ios, '13.0'

target 'YourApp' do
  pod 'ReflectSDK',  :git => 'https://github.com/bablu147/reflect-sdk-ios.git', :tag => '1.0.1'
  pod 'ReflectCore', :git => 'https://github.com/bablu147/reflect-ios.git',     :tag => '1.1.4'
end

LANG=en_US.UTF-8 pod install

pod needs a UTF-8 locale or it crashes inside unicode_normalize. Afterwards open the generated .xcworkspace, never the.xcodeproj.

Pin both tags exactly. ReflectCore 1.1.4 fixes first-session delivery (install latched at durable persistence, retry ladder, activation + background flush); 1.1.3 fixes jailbreak detection false-positiving on all real iPhones; 1.1.2 adds the batch-size/byte clamps; 1.1.1 is the first core release that does not brand every event flutter on the wire; 1.1.0 carries the privacy engine but has that branding bug, and 1.0.0 predates the privacy engine this facade's gate assumes. Neither is a valid target.

Swift Package Manager is not supported

Requirements

• iOS 13.0+, Swift 5.0+, Xcode 15+
• Depends on the shared ReflectCore engine (~> 1.1, resolving to 1.1.4) — no other third-party dependencies
• AdServices and AppTrackingTransparency are weak-linked; AdAttributionKit is deliberately not linked
• Sends sdk_version = ios-1.0.0 on the wire, to https://api.reflect.cloud by default

Quick start

Swift — UIKit AppDelegate

import ReflectSDK

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // 1. Listeners first.
        Reflect.onDeepLink { link in
            print("deep link:", link.url, link.path ?? "", link.source)   // .cold / .warm / .deferred
        }
        Reflect.onAttributionChanged { attribution in
            print("partner:", attribution.partner ?? "-")
        }

        // 2. Capture the cold-launch URL (buffered in memory, replayed after init).
        Reflect.application(application, didFinishLaunchingWithOptions: launchOptions)

        // 3. Initialize.
        Reflect.initialize(ReflectConfig(
            appKey: "YOUR_APP_KEY",
            signingSecret: "YOUR_APP_HMAC_SECRET",   // required for shared_hmac apps
            debug: true
        ))
        return true
    }
}

// Anywhere afterwards:
Reflect.setUserId("user_123")
Reflect.trackEvent("level_complete", properties: ["level": 5, "score": 42_000])
Reflect.trackEvent(.purchase)                       // type-safe standard name

// async twins where a value comes back:
let attribution = await Reflect.getAttribution()
let link        = await Reflect.getInitialDeepLink()

Objective-C — same app, no Swift

@import ReflectSDK;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. Listeners first.
    [RFLReflect onDeepLink:^(RFLDeepLinkData *link) {
        NSLog(@"deep link: %@ %@", link.url, link.path ?: @"");
    }];
    [RFLReflect onAttributionChanged:^(RFLAttributionData *attribution) {
        NSLog(@"partner: %@", attribution.partner ?: @"-");
    }];

    // 2. Capture the cold-launch URL.
    [RFLLifecycle application:application didFinishLaunchingWithOptions:launchOptions];

    // 3. Initialize.
    RFLConfig *config = [[RFLConfig alloc] initWithAppKey:@"YOUR_APP_KEY"];
    config.signingSecret = @"YOUR_APP_HMAC_SECRET";
    config.debug = YES;
    [RFLReflect initializeWithConfig:config];
    return YES;
}

@end

// Anywhere afterwards:
[RFLReflect setUserId:@"user_123"];
[RFLReflect trackEvent:@"level_complete" properties:@{@"level": @5}];

// Completion-handler twins of the async methods:
[RFLReflect getAttributionWithCompletion:^(RFLAttributionData *a) { /* main queue */ }];
[RFLReflect getInitialDeepLinkWithCompletion:^(RFLDeepLinkData *link) { /* main queue */ }];

New apps default to server policy shared_hmac: signingSecret is required, and unsigned traffic is rejected with signature_required. Inject the value through ignored local/CI configuration; never commit a real one.

App lifecycle wiring

The core installs no URL handling of its own — iOS delivers URLs toyour delegate and there is no supported way to intercept that. Everything below is one line per callback.

(a) UIKit — AppDelegate only

func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    Reflect.handle(url: url)
    return false                       // observe only; don't claim exclusive handling
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    Reflect.continue(userActivity: userActivity)
    return false
}

Objective-C uses [RFLLifecycle handleURL:url] and [RFLLifecycle continueUserActivity:userActivity].

(b) UIKit — SceneDelegate

Keep the listeners and initialize in the AppDelegate; the scene supplies the link. With scenes, launchOptions is usually empty — callingReflect.application(_:didFinishLaunchingWithOptions:) anyway is harmless and keeps the non-scene path working.

func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {
    Reflect.scene(willConnectWith: connectionOptions)   // covers urlContexts AND userActivities
}

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    Reflect.scene(openURLContexts: URLContexts)
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    Reflect.continue(userActivity: userActivity)
}

(c) SwiftUI

The SwiftUI App lifecycle has no delegate by default, so use the view modifiers:

@main
struct SampleApp: App {
    init() {
        Reflect.onDeepLink { DeepLinkRouter.shared.handle($0) }
        Reflect.onAttributionChanged { AttributionStore.shared.update($0) }
        Reflect.initialize(ReflectConfig(appKey: "YOUR_APP_KEY",
                                         signingSecret: "YOUR_APP_HMAC_SECRET"))
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { Reflect.handle(url: $0) }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) {
                    Reflect.continue(userActivity: $0)
                }
        }
    }
}

Info.plist keys

None of this can be automated for a native app — there is no build post-processor here.

The SDK ships its own PrivacyInfo.xcprivacy inside ReflectSDK.bundle, but a bundle manifest cannot declare NSPrivacyTrackingDomains on your behalf — that one belongs to your app.

App Tracking Transparency

Reflect.requestTrackingAuthorization { status in
    // .authorized / .denied / .restricted / .notDetermined / .gateClosed / .unavailable
}

let status = await Reflect.requestTrackingAuthorization()   // async twin

// Raw wire string, for parity with the Flutter/RN surface:
Reflect.requestTrackingAuthorizationRaw { raw in /* "authorized" | "denied" | ... */ }

[RFLReflect requestTrackingAuthorizationWithCompletion:^(RFLTrackingStatus status) {
    NSLog(@"ATT: %ld", (long)status);
}];

The tracking-domain transport gate. An app that declares its ingest host inNSPrivacyTrackingDomains — an opt-in posture; the default since 2026-08 is to leave the host undeclared — has every connection to that host refused by iOS until ATT is answered. It surfaces asNSURLErrorNotConnectedToInternet while the status is stillnot_determined. The core recognises exactly that pair, parks the drain against a 5-minute ceiling and persists no backoff deadline, so the queue is preserved and flushes once the prompt is answered. A denial does not reopen the domain. "No events until the second launch" is almost always this, not a bug.

SKAdNetwork

SKAN is armed automatically on first launch (unless autoRegisterSkan: false), and conversion values are driven automatically from trackRevenue,trackPurchase and trackSubscription using a bucket schema fetched from GET {baseUrl}/skan/cv-schema?app_key=… (24 h TTL, exactly 64 entries).Without a cached schema no conversion value is ever sent — the SDK never invents buckets. Non-increasing updates are suppressed.

Reflect.updateConversionValue(7, coarseValue: "medium", lockWindow: false) { result in
    if result.success { print("sent via", result.method ?? "-") }
    else { print("failed:", result.error ?? "-") }
}

// async twin — the completion parameter has NO default value, so that
// Reflect.updateConversionValue(7) inside an async function is unambiguous.
let result = await Reflect.updateConversionValue(7)

[RFLReflect updateConversionValue:7 coarseValue:@"medium" lockWindow:NO
                       completion:^(RFLConversionValueResult *r) { /* ... */ }];

A fineValue outside 0...63 fails client-side withfine_value_out_of_range before anything is dispatched. Other failure codes:measurement_disabled, privacy_state_changed,skan_not_available, collection_blocked (the privacy gate refused).

Privacy & consent

The facade runs its own fail-closed gate in front of the core's — the same contract the native Android SDK implements. It exists for two reasons the core cannot cover: there is no server-side PII strip for the sticky email the facade injects, and the bridge is asynchronous while the public API is not — setConsent(false) must closesynchronously at the call boundary, because the app has already told the user they opted out.

Reflect.setConsent(false) { persisted in /* false => the denial did not durably persist */ }
Reflect.setEmail("[email protected]")        // ignored while denied
Reflect.trackEvent("checkout")              // dropped while denied

Reflect.setConsent(true) { _ in }           // waits for native confirmation
Reflect.setEmail("[email protected]")        // re-supply after the grant

• setConsent, setEnabled, setAdvertisingConsent and setThirdPartySharing each take an optional completion carrying a Bool. The core returns real privacy_persistence_failed errors on exactly these four — without the completion you could never learn that a GDPR opt-out failed to persist.
• Pass the raw email; the server hashes it. Never hash it yourself. It stays sticky until clearEmail(), a consent denial, deleteUserData(), or replacement.
• setEnabled(false) suppresses reversibly; a consent denial or deleteUserData() destroys irreversibly. Only the latter clears the facade's local email, global-property and deep-link caches.
• Calls made before initialize are folded into the init arguments, but only the restrictive ones: a pre-init setConsent(false) / setEnabled(false) is carried forward, a pre-init grant is not.
• During warm-up (initialize issued, posture not yet read back) measurement calls wait in a bounded FIFO. If the readback fails the gate stays closed and the FIFO is discarded — an unknown posture is treated as a denial.

See Privacy & consent for the server-side model.

API surface

Every method below is available from Objective-C on RFLReflect under an explicitRFL* selector. Methods that return a value also have an async twin in Swift (getAttribution, getAttributionWithTimeout,getInitialDeepLink, getLastDeepLink, resolveDeepLink,getInstallUuid, isEnabled, deleteUserData,verifyPurchase, verifyAndTrackPurchase,requestTrackingAuthorization, updateConversionValue,getDebugState).

getAttributionWithTimeout takes milliseconds(timeoutMs: Int = 3000, clamped to 0...3_600_000) — named that way deliberately, because a developer carrying the Flutter/RN habit of passing 3000to a TimeInterval would otherwise get 3000 seconds.

Troubleshooting