Apple Search Ads Attribution

AppActor includes built-in Apple Search Ads (ASA) attribution tracking. When enabled, the SDK automatically captures attribution data, tracks purchases linked to ASA campaigns, and syncs user identity changes.

Overview

Enabling ASA Tracking

Pass AppActorASAOptions when configuring the SDK in payment mode:

iOS
Android
Flutter
React Native

AppActor.configure(
  apiKey: "pk_live_abc123",
  options: .init(
      asa: AppActorASAOptions(
          autoTrackPurchases: true,  // Automatically track purchase events
          trackInSandbox: false,     // Track sandbox events during development
          debugMode: false           // Enable verbose ASA logging
      )
  )
)

Option	Default	Description
`autoTrackPurchases`	`true`	Automatically enqueue ASA purchase events when StoreKit transactions are processed
`trackInSandbox`	`false`	Track sandbox/TestFlight/StoreKit test purchase events for debugging
`debugMode`	`false`	Enable verbose ASA-specific logging

When options.asa is nil (the default), no ASA code runs and no ASA network calls are made.

How It Works

Attribution Flow

The SDK calls AAAttribution.attributionToken() from Apple's AdServices framework
The token is sent to the AppActor backend along with device info
The server resolves the attribution (campaign, ad group, keyword, etc.)

Organic installs (no token available): immediately marked as completed, no server call
Retries exhausted: retries on next app launch

Purchase Event Tracking

When autoTrackPurchases is enabled, the SDK automatically links purchases to ASA campaigns:

Events are persisted to disk and survive app termination. The queue is flushed during bootstrap and when the app returns to the foreground.

User Identity Sync

When users log in or out, the SDK syncs the identity change with the ASA system:

iOS
Android
Flutter
React Native

// This happens automatically when you call:
try await AppActor.shared.logIn(newAppUserId: "user_123")
// The SDK internally calls:
// asaManager.enqueueUserIdChange(oldUserId: "anon_abc", newUserId: "user_123")

Diagnostics

Check the status of ASA tracking:

iOS
Android
Flutter
React Native

// Point-in-time diagnostic snapshot
if let diag = await AppActor.shared.asaDiagnostics() {
  print("Attribution completed: \(diag.attributionCompleted)")
  print("Pending events: \(diag.pendingPurchaseEventCount)")
  print("Debug mode: \(diag.debugMode)")

  if let change = diag.pendingUserIdChange {
      print("Pending identity: \(change.oldUserId) → \(change.newUserId)")
  }
}

// Quick pending count
let count = await AppActor.shared.pendingASAPurchaseEventCount

Storage

Key / File	Purpose
`appactor_asa_attribution_completed`	Prevents redundant attribution calls
`appactor_asa_pending_old_user_id`	Old user ID for pending identity change
`appactor_asa_pending_new_user_id`	New user ID for pending identity change
`Library/Application Support/appactor/asa_events.json`	Purchase event retry queue (survives app termination)

Requirements

AdServices framework — Available on iOS 14.3+. The SDK gracefully handles unavailability.
Payment mode only — ASA tracking requires a backend connection.

Next Steps

Sandbox Testing — Test purchases in sandbox
Launch Checklist — Pre-launch checklist

Overview​

Enabling ASA Tracking​

How It Works​

Attribution Flow​

Purchase Event Tracking​

User Identity Sync​

Diagnostics​

Storage​

Requirements​

Next Steps​