iOS SDK Integration

Overview

The SDK needs iOS 13 or later and is installed with Swift Package Manager. It reports the install once, sends each event with its own ID so a retry is never counted twice, and saves events on the device until they are delivered.

Before you start, add your app under Mobile Apps in the dashboard and open its SDK & Links tab. You need the app key, the SDK signing secret and your tracking domain. Mobile Apps is enabled per account: contact support if you do not see it.

Install

In Xcode choose File → Add Package Dependencies and enter the package URL:

https://github.com/affclix/affclix-ios-sdk

Start the SDK

Call start once, as early as possible:

import AffclixSDK

// application(_:didFinishLaunchingWithOptions:)
Affclix.start(AffclixConfig(
    appKey: "YOUR_APP_KEY",
    appSecret: Secrets.affclixAppSecret,
    trackingDomain: "track.yourbrand.com",
    attWaitTimeout: 60,
    onDeepLink: { link in route(link.deepLinkValue) },
    deferredDeepLinking: .automatic
))

App Tracking Transparency

Add NSUserTrackingUsageDescription to Info.plist, then ask at a moment that suits your onboarding:

Affclix.requestTrackingAuthorization { status in }

With attWaitTimeout set, the install waits that many seconds for the answer, so it can carry the IDFA. If the user declines, the install is still recorded, without the IDFA.

In-App Events

Send your own event names. Which campaign goal each one books is set under Settings → Events, so it can change without an app release.

Affclix.logEvent("registration")
Affclix.logEvent("level_complete", params: ["level": 3])

An event with no goal is still recorded, but no conversion is created for it.

Revenue

Affclix.logPurchase(revenue: 4.99, currency: "USD",
                    transactionID: orderID, eventToken: "purchase")

// StoreKit 2: validated with Apple when your App Store key is in Settings
Affclix.logAppStorePurchase(transactionID: transaction.id, productID: transaction.productID,
                            revenue: 4.99, currency: "USD", eventToken: "purchase")

Affclix.logAdRevenue(network: "applovin", revenue: 0.0021, adFormat: "rewarded")

Always send your order ID as the transaction ID: a second conversion with the same ID is rejected, so a repeated call is not paid twice.

Deep Links

Pass every link that opens the app to the SDK. It keeps the click, and later events are credited to it.

Affclix.handleDeepLink(url)                  // application(_:open:options:)
Affclix.continueUserActivity(userActivity)   // application(_:continue:restorationHandler:)

For Universal Links, enter your Apple Team ID under Settings → Deep Links and add applinks:your-tracking-domain to the app's Associated Domains. This needs a paid Apple Developer account.

Deferred Deep Links

These keep the click when the app is not installed yet. Turn on iOS deferred deep linking under Settings → Deep Links and use .automatic or .manual in the SDK.

1. The user taps your link and sees a Continue to the App Store page.
2. Tapping Continue copies a one-time link, valid for 24 hours, to the clipboard.
3. On first launch the SDK reads it. With .automatic, iOS asks the user to allow the paste. With .manual, your own system Paste button replaces that prompt.
4. The install is credited to the click, and onDeepLink receives the link with isDeferred set.

For a campaign, copy the destination URL from SDK & Links: on an iOS app with this setting on, it already goes through the handoff page. If you turned the setting on later, paste the new URL into your existing campaigns.

SKAdNetwork

The SDK registers the app on first launch and sets conversion values from the schema in your dashboard. To receive Apple's postbacks, set NSAdvertisingAttributionReportEndpoint in Info.plist to https://your-tracking-domain. If you set values yourself, turn off automaticConversionValues so the two do not compete.

Consent & Deletion

Affclix.setConsentData(isUserSubjectToGDPR: true,
                       hasConsentForDataUsage: false,
                       hasConsentForAdsPersonalization: false)

Affclix.requestDataDeletion { result in }

When a user refuses ad data use, their device ID is not used for matching. Set enableTCFDataCollection to read consent from your CMP instead.

requestDataDeletion removes the device's data from mobile attribution and clears its identifiers on the device. Conversions already credited to an affiliate stay in your campaign reports.

Uninstall Tracking

Add your APNs auth key under Settings → Uninstall Tracking, then enable Push Notifications and the Remote notifications background mode.

func application(_ app: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken token: Data) {
    Affclix.setPushToken(token, sandbox: isDebugBuild)
}

func application(_ app: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler done: @escaping (UIBackgroundFetchResult) -> Void) {
    if Affclix.isUninstallCheck(userInfo) { return done(.noData) }
    // your own notifications
}

Test Your Integration

1. Add your device's IDFV or IDFA under the Test Devices tab. Install and event requests then appear in Live Test Events within seconds, with anything missing listed beside them.
2. Test devices can install repeatedly, but they never create conversions. To check a real conversion, remove the device and click a campaign's tracking link.
3. Check the Setup checklist on SDK & Links. It shows Ready once your app is sending data and a campaign is linked.

Troubleshooting