Documentation
SDKappsprint-ios

iOS (Swift)

Installation, configuration, event tracking, and full API reference for the iOS (Swift) SDK.

Requirements

  • iOS 14.0+
  • Xcode 15+
  • Swift concurrency (async/await)

1. Install

Swift Package Manager

// In Xcode: File → Add Package Dependencies…
// Or in Package.swift:
.package(url: "https://github.com/app-sprint/appsprint-ios.git", from: "0.1.0")

2. Configure

import AppSprintSDK


// Call as early as possible — App.init() or AppDelegate
await AppSprint.shared.configure(
  AppSprintConfiguration(apiKey: "as_live_xxxxx")
)

Must run on the main thread (@MainActor). The SDK automatically tracks the install on first launch and flushes any queued events.

Configuration options

OptionTypeDefaultDescription
apiKeyString—Your live API key (starts with as_live_).
apiURLURLhttps://api.appsprint.appOverride the API base URL for testing.
enableAppleAdsAttributionBooltrueFetch the AdServices attribution token on first launch.

3. Track events

// Standard event
await AppSprint.shared.sendEvent("login")
// Revenue event
await AppSprint.shared.sendEvent("purchase", revenue: 9.99, currency: "USD")
// Custom event with parameters
await AppSprint.shared.sendEvent("level_complete", parameters: [
  "level": 5,
  "score": 1200,
])

Supported event types

loginsign_upregisterpurchasesubscribestart_trialadd_to_cartadd_to_wishlistinitiate_checkoutview_contentview_itemsearchsharetutorial_completelevel_startlevel_completecustom

Use custom with a name parameter for any event not in this list.

4. Read attribution

After configure() completes, the SDK caches the attribution result from the install response. Access it synchronously:

let attr = AppSprint.shared.getAttribution()
print(attr?.source)       // "apple_ads", "fingerprint", or "organic"
print(attr?.confidence)   // 0.0–1.0
print(attr?.campaignName) // Campaign name if available
FieldDescription
source"apple_ads", "fingerprint", or "organic"
confidenceMatch confidence from 0.0 to 1.0
campaignNameCampaign name (if attributed to an ad)
utmSourceUTM source from the tracking link
utmMediumUTM medium from the tracking link
utmCampaignUTM campaign from the tracking link

API reference

configure(_:)

→ async

Initialize the SDK. Auto-tracks install on first launch and flushes queued events.

await AppSprint.shared.configure(AppSprintConfiguration(apiKey: "…"))

sendEvent(_:revenue:currency:parameters:)

→ async

Send an event. Queued automatically if offline or not yet initialized.

await AppSprint.shared.sendEvent("purchase", revenue: 9.99, currency: "USD")

flush()

→ async

Retry all queued events immediately.

await AppSprint.shared.flush()

clearData()

Clear all cached state, queue, and disabled flag. Use to reset the SDK.

AppSprint.shared.clearData()

getAppSprintId()

→ String?

Returns the install ID, or nil before install tracking completes.

let id = AppSprint.shared.getAppSprintId()

getAttribution()

→ AttributionData?

Returns cached attribution data from the install response.

let attr = AppSprint.shared.getAttribution()

isInitialized

→ Bool

True once configure() has completed.

AppSprint.shared.isInitialized

sendTestEvent()

→ TestEventResult

Send a diagnostic event. Returns success/message — use to verify connectivity.

let result = await AppSprint.shared.sendTestEvent()

setCustomerUserId(_:)

→ async

Attach your own user ID. Sent to the API immediately if install is tracked, otherwise queued.

await AppSprint.shared.setCustomerUserId("user-123")

Offline behavior

  • Events that fail to send are automatically queued in native storage (up to 100 events).
  • The queue persists across app restarts.
  • Queued events are retried automatically when configure() completes, when the app moves to the background, or when you call flush().
  • If a queued event receives a 401/403, the SDK disables itself and clears the queue.

Platform notes

  • The SDK calls AdServices.AAAttribution.attributionToken() on iOS 14.3+ to detect Apple Search Ads installs. On older versions it falls back to the iAd framework.
  • IDFA is only collected if the user has granted App Tracking Transparency permission. IDFV is always collected.
  • configure() is annotated @MainActor — call it from the main thread or an async context that already runs on main.
  • The event queue flushes automatically when the app moves to the background.

Integrations

Once the SDK is configured, connect revenue and ad-network integrations:

RevenueCat
Attribute subscriptions and purchases
Superwall
Attribute paywall conversions
Apple Search Ads
Campaign and keyword attribution

Troubleshooting

getAppSprintId() returns nil

configure() is async — the install network call may not have finished yet. Wait for configure() to complete before reading the ID.

Events not appearing in dashboard

Check that you are using a live API key (as_live_*). Call sendTestEvent() and inspect the result message.

SDK disabled after 401/403

The SDK disables itself permanently when the API key is rejected. Call clearData() and re-configure with a valid key.

Apple Ads attribution missing

Ensure AdServices.framework is linked. Test on a real device — the simulator does not return attribution tokens.

Connectivity test

let result = await AppSprint.shared.sendTestEvent()
print("\(result.success) — \(result.message)")

Verification checklist

  1. Create a blank iOS app and add the Swift package.
  2. Call configure() in your App or AppDelegate entry point.
  3. Verify getAppSprintId() returns a value after first launch.
  4. Send login, purchase, and custom events — confirm they appear in the dashboard.
  5. Kill the app while offline, send an event, relaunch with connectivity — verify the event appears (queue flush).
  6. Call sendTestEvent() and confirm { success: true }.