Getting started with the iOS SDK

This guide walks you through the initial setup of the Adtrace iOS SDK. You'll learn how to install the SDK, configure your project, initialize the SDK, and verify that your integration is successful. By the end of this guide, your app will be ready to track installs, sessions, and events.

Example apps: Objective-C, Swift, WebView (experimental).

1. Add the Adtrace SDK

Add the Adtrace SDK to your iOS project using one of these methods:

• CocoaPods (recommended): add the pod to your Podfile and run pod install.
• Carthage: add the SDK to your Cartfile.
• Swift Package Manager: add the GitHub repository in Xcode.

Check the releases page for the latest stable version.

Important

The Adtrace iOS SDK supports iOS 9 or later.

CocoaPods

Add the SDK to your Podfile:

Podfile

# From the CocoaPods repository
pod 'Adtrace', '~> 2.2.1'

# Or directly from GitHub
pod 'Adtrace', :git => 'https://github.com/adtrace/adtrace_sdk_iOS.git', :tag => '2.2.1'

Carthage

Add the following to your Cartfile:

Cartfile

github "adtrace/ios_sdk"

Swift Package Manager

1. In Xcode, click File → Add Package Dependencies.
2. Enter the SDK repository URL:

https://github.com/adtrace/adtrace_sdk_iOS

3. Select the Adtrace SDK version in the Version dropdown.

2. Integrate the SDK

Import the Adtrace SDK in your app delegate (or bridging header for Swift).

CocoaPods

Objective-C

Add to AppDelegate.h:

AppDelegate.h

#import "Adtrace.h"
// or
#import <Adtrace/Adtrace.h>

For WebBridge (experimental), also add:

AppDelegate.h

#import "AdtraceBridge.h"

Swift

Add to your bridging header:

Bridging-Header.h

#import <Adtrace/Adtrace.h>

For WebBridge (experimental), also add:

Bridging-Header.h

#import "AdtraceBridge.h"

Carthage or framework import

Objective-C

AppDelegate.h

#import <AdtraceSdk/Adtrace.h>

For WebBridge (experimental):

AppDelegate.h

#import <AdtraceSdkWebBridge/AdtraceBridge.h>

Swift

Bridging-Header.h

#import <Adtrace/Adtrace.h>

For WebBridge (experimental):

Bridging-Header.h

#import <AdtraceSdkWebBridge/AdtraceBridge.h>

3. Add iOS frameworks

The Adtrace SDK can use optional Apple frameworks for additional features. Add them in Xcode and mark each as Optional so the SDK still runs when a framework is unavailable.

Framework	Purpose	Notes
AdSupport.framework	Read IDFA and (before iOS 14) LAT	Do not add for Kids category apps
AdServices.framework	Apple Search Ads attribution
StoreKit.framework	SKAdNetwork communication (iOS 14+)
AppTrackingTransparency.framework	ATT consent dialog (iOS 14+)	Do not add for Kids category apps
WebKit.framework	WebView support	Only for WebBridge / WebView apps

For ATT setup, see App Tracking Transparency.

4. Initialize the Adtrace SDK

Initialize AdtraceConfig with your app token and environment, then call appDidLaunch from application:didFinishLaunchingWithOptions: in your app delegate.

You need:

• appToken: your Adtrace app token from the Adtrace panel
• environment: use ADTEnvironmentSandbox while testing and ADTEnvironmentProduction before you publish. Adtrace uses this to separate test traffic from real traffic.

Important

Use ADTEnvironmentSandbox while testing. Switch to ADTEnvironmentProduction before you submit to the App Store or release the app.

Objective-C

AppDelegate.m

#import "Adtrace.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSString *yourAppToken = @"{YourAppToken}";
    NSString *environment = ADTEnvironmentSandbox;
    ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                                   environment:environment];

    [Adtrace appDidLaunch:adtraceConfig];
    return YES;
}

Swift

AppDelegate.swift

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    let yourAppToken = "{YourAppToken}"
    let environment = ADTEnvironmentSandbox
    let adtraceConfig = ADTConfig(appToken: yourAppToken, environment: environment)

    Adtrace.appDidLaunch(adtraceConfig)
    return true
}

Replace {YourAppToken} with your app token from the Adtrace panel.

Set environment based on your stage:

Objective-C

// Testing
NSString *environment = ADTEnvironmentSandbox;

// Production (before release)
NSString *environment = ADTEnvironmentProduction;

Swift

// Testing
let environment = ADTEnvironmentSandbox

// Production (before release)
let environment = ADTEnvironmentProduction

5. Set up logging

Set logLevel on your ADTConfig before calling appDidLaunch. For full options and production suppress mode, see Set log level.

Note

To disable all logging, set allowSuppressLogLevel to YES / true on AdtraceConfig and use ADTLogLevelSuppress.

Objective-C

AppDelegate.m

[adtraceConfig setLogLevel:ADTLogLevelVerbose]; // enable all logging
[adtraceConfig setLogLevel:ADTLogLevelDebug];
[adtraceConfig setLogLevel:ADTLogLevelInfo];    // default
[adtraceConfig setLogLevel:ADTLogLevelWarn];
[adtraceConfig setLogLevel:ADTLogLevelError];
[adtraceConfig setLogLevel:ADTLogLevelAssert];
[adtraceConfig setLogLevel:ADTLogLevelSuppress]; // disable all logging

Swift

AppDelegate.swift

adtraceConfig?.logLevel = ADTLogLevelVerbose // enable all logging
adtraceConfig?.logLevel = ADTLogLevelDebug
adtraceConfig?.logLevel = ADTLogLevelInfo    // default
adtraceConfig?.logLevel = ADTLogLevelWarn
adtraceConfig?.logLevel = ADTLogLevelError
adtraceConfig?.logLevel = ADTLogLevelAssert
adtraceConfig?.logLevel = ADTLogLevelSuppress // disable all logging

To suppress logs in production builds, initialize with allowSuppressLogLevel:

Objective-C

AppDelegate.m

NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADTEnvironmentProduction;
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                             environment:environment
                                     allowSuppressLogLevel:YES];

[Adtrace appDidLaunch:adtraceConfig];

Swift

AppDelegate.swift

let yourAppToken = "{YourAppToken}"
let environment = ADTEnvironmentProduction
let adtraceConfig = ADTConfig(
    appToken: yourAppToken,
    environment: environment,
    allowSuppressLogLevel: true
)

Adtrace.appDidLaunch(adtraceConfig)

6. WebBridge

Optional. Only for apps that use a WKWebView. Native-only apps can skip to 7. Test the integration.

Show WebBridge setup (WebView apps, experimental)

Complete the native setup above first (SDK, frameworks, initialize, and logging). Then connect WebBridge in your view controller and web content.

See the WebView example app for a full reference.

Connect WebBridge in your view controller

Objective-C

ViewController.m

#import "AdtraceBridge.h"

- (void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];

    WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds];
    // Add @property (nonatomic, strong) AdtraceBridge *adtraceBridge; to your interface
    [self.adtraceBridge loadWKWebViewBridge:webView];
}

Swift

ViewController.swift

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)

    let webView = WKWebView(frame: view.bounds)
    // Add var adtraceBridge: AdtraceBridge? to your interface
    adtraceBridge?.loadWKWebViewBridge(webView)
}

You can also use the included WebViewJavascriptBridge via the bridgeRegister property on your AdtraceBridge instance. See the library documentation.

Initialize Adtrace in your web view

web view init

function setupWebViewJavascriptBridge(callback) {
  if (window.WebViewJavascriptBridge) {
    return callback(WebViewJavascriptBridge);
  }

  if (window.WVJBCallbacks) {
    return window.WVJBCallbacks.push(callback);
  }

  window.WVJBCallbacks = [callback];

  const WVJBIframe = document.createElement('iframe');
  WVJBIframe.style.display = 'none';
  WVJBIframe.src = 'https://__bridge_loaded__';
  document.documentElement.appendChild(WVJBIframe);

  setTimeout(function () {
    document.documentElement.removeChild(WVJBIframe);
  }, 0);
}

setupWebViewJavascriptBridge(function (bridge) {
  const yourAppToken = '{YourAppToken}';
  const environment = AdtraceConfig.EnvironmentSandbox;
  const adtraceConfig = new AdtraceConfig(yourAppToken, environment);
  Adtrace.appDidLaunch(adtraceConfig);
});

Optional: iMessage extension

Optional. Only if your app includes an iMessage app extension. Apps without a Messages extension can skip to 7. Test the integration.

iMessage extensions need extra SDK setup and manual session hooks (trackSubsessionStart / trackSubsessionEnd). Use a separate app token for the extension.

See iMessage extension setup for full steps, method signatures, and a checklist.

7. Test the integration

A successful install (first open after install) must be recorded before sessions and events appear correctly in Adtrace. Use the steps below to verify your integration.

Prepare a clean test device

To trigger a real install for testing:

1. Use a device that has never installed your app, or uninstall the app from the device.
2. Install and open the app again on a clean state.
3. If you already tested on the same device, use Forget Device in the Testing Console (see below).

Test in the Adtrace panel

If you use the Adtrace panel:

1. Copy your device ID (IDFA if available, otherwise primary_dedupe_token from SDK logs).
2. Open the Adtrace panel, select your app, then go to Settings → Testing Console.
3. Enter the device ID, choose the ID type (idfa or the matching type shown in the console), and check whether an install is recorded for that device.

If no install appears, review the earlier setup steps and the example apps, then try again on a clean device. See FAQ for troubleshooting.

Test with logs (optional)

1. Set logLevel to ADTLogLevelVerbose and environment to ADTEnvironmentSandbox.
2. Connect the device and open Xcode console logs.
3. Uninstall the app if needed, reinstall, and open the app.
4. In the server response logs, look for an adid value. Receiving adid means the install was recorded successfully.

Console response (example)

"adid" : "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

8. Build your app for production

After you finish testing, update your AdtraceConfig before you ship the app:

1. Set logLevel to ADTLogLevelWarn or ADTLogLevelSuppress for production.
2. Set environment to ADTEnvironmentProduction.

Objective-C

AppDelegate.m

NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADTEnvironmentProduction;
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                             environment:environment
                                     allowSuppressLogLevel:YES];
[adtraceConfig setLogLevel:ADTLogLevelWarn];

[Adtrace appDidLaunch:adtraceConfig];

Swift

AppDelegate.swift

let yourAppToken = "{YourAppToken}"
let environment = ADTEnvironmentProduction
let adtraceConfig = ADTConfig(
    appToken: yourAppToken,
    environment: environment,
    allowSuppressLogLevel: true
)
adtraceConfig?.logLevel = ADTLogLevelWarn

Adtrace.appDidLaunch(adtraceConfig)

Sandbox and production traffic are separated in the Adtrace panel, so you can filter test data from real users.

You are ready to build and run your production app and start attributing users with the Adtrace SDK.

Checklist

Before you move on, confirm you have completed:

• Added the Adtrace SDK (CocoaPods, Carthage, or SPM)
• Imported the SDK in your app delegate or bridging header
• Added required optional iOS frameworks for your use case
• Initialized Adtrace in application:didFinishLaunchingWithOptions:
• Set sandbox environment and verbose logs for testing
• Verified a successful install in Testing Console or logs
• Switched to ADTEnvironmentProduction for release

Next steps

• Event tracking
• Configuration
• Additional Features
• FAQ