Skip to main content

Basic Setup

This is the iOS SDK of Adtrace. You can read more about Adtrace at our website.

Example Apps​

Objective-C Example app
Swift Example app
Webview Example app (experimental)

Basic integration​

The Adtrace iOS SDK enables you to track attribution, events, and much more in your iOS app. Follow the steps in this guide to set up your app to work with the Adtrace SDK.

Set up your environment​

To start using the Adtrace SDK, you will first need to add it to your project as a dependency.

Important

The Adtrace SDK supports iOS 9 or later.

Cocoapods

To add the SDK using Cocoapods, specify the version you want to use in your Podfile:

// Get pod from repository
pod 'Adtrace', '~> 2.2.1'

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

To add the SDK using Carthage, add the following to your Cartfile:

github "adtrace/ios_sdk"
Swift package manager

To add the SDK using Swift's package manager:

  1. Click File.
  2. Select Swift Packages.
  3. Select Add Package Dependency.
  4. In the box that appears, enter the SDK's GitHub address.
https://github.com/adtrace/adtrace_sdk_iOS
  1. Select the version of the Adtrace SDK you want to use in the Version dropdown. Check the releases page for the latest stable version.

Integrate the SDK​

Cocoapods

If you added the Adtrace SDK via a Pod repository, you will need to import the relevant import statement to your project:

Add the following to your AppDelegate.h file:

#import "Adtrace.h"

//or

#import <Adtrace/Adtrace.h>

If you are using the Adtrace Web Bridge, add the following to your AppDelegate.h file:

#import "AdtraceBridge.h"
Carthage and framework import

If you added the Adtrace SDK as a static or dynamic framework or via Carthage, use the following import statement:

Add the following to your AppDelegate.h file:

#import <AdtraceSdk/Adtrace.h>

If you are using the Adtrace Web Bridge, add the following to your AppDelegate.h file:

#import <AdtraceSdkWebBridge/AdtraceBridge.h>

Add iOS frameworks​

The Adtrace SDK is able to get extra information when you include certain iOS frameworks in your app. Adding frameworks and marking them as optional enables additional features in the Adtrace SDK.

FrameworkDescriptionNotes
AdSupport.frameworkThis framework is needed so that the SDK can access the IDFA value and – prior to iOS 14 – LAT information.If your app is targeting the "Kids" category, you should not implement this framework.
AdServices.frameworkThis framework is needed to handle Apple Search Ads attribution.
StoreKit.frameworkThis framework is needed to access the SKAdNetwork framework and for the Adtrace SDK to handle communication with it automatically in iOS 14 or later.
AppTrackingTransparency.frameworkThis framework is needed in iOS 14 and later for the SDK to be able to wrap the user tracking consent dialog and access the user’s consent response.If your app is targeting the "Kids" category, you should not implement this framework.
WebKit.framework (Experimental)This framework allows you to make use of web views in your application.This is only needed if your app makes use of web views.

Initialize the SDK​

Once you've added all necessary frameworks, you can initialize the Adtrace SDK within your application. To do this, initialize your ADTConfig object with your app token and the environment you want to run your application in.

Important

When running tests you should ensure that your environment is set to ADTEnvironmentSandbox. Change this to ADTEnvironmentProduction before you submit your application to the App Store or release it any other way.

Standard App

In the Project Navigator, open the source file of your application delegate. Add the import statement at the top of the file. Next, add the following call to Adtrace in the didFinishLaunching or didFinishLaunchingWithOptions method of your app delegate:

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

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

[Adtrace appDidLaunch:adtraceConfig];
Web Bridge App (Experimental)

Follow these steps to integrate the Adtrace Web bridge into your app.

Integrate AdtraceBridge into your app​

In the Project Navigator, open the source file of your View Controller. Add the import statement at the top of the file. Add the following calls to AdtraceBridge in the viewDidLoad or viewWillAppear method of your Web View Delegate:

#import "AdtraceBridge.h"
// or #import <AdtraceSdkWebBridge/AdtraceBridge.h>

- (void)viewWillAppear:(BOOL)animated {
WKWebView * webView = [[WKWebView alloc] initWithFrame:self.view.bounds];

// add @property (nonatomic, strong) AdtraceBridge *adtraceBridge; on your interface
[self.adtraceBridge loadWKWebViewBridge:webView];
// optionally you can add a web view delegate so that you can also capture its events
// [self.adtraceBridge loadWKWebViewBridge:webView wkWebViewDelegate:(id<WKNavigationDelegate>)self];
}

// ...

You can also make use of the included WebViewJavascriptBridge. You can use this by setting the bridgeRegister property of your AdtraceBridge instance. See the library's documentation for usage information.

Integrate AdtraceBridge into your web view​

To use the Javascript bridge in your web view, you need to configure the bridge. Include the following Javascript code to initialize the Adtrace iOS web bridge:

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

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

window.WVJBCallbacks = [callback];

var 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) {
// ...
var yourAppToken = yourAppToken;
var environment = AdtraceConfig.EnvironmentSandbox;
var adtraceConfig = new AdtraceConfig(yourAppToken, environment);
Adtrace.appDidLaunch(adtraceConfig);
// ...
});

Set up logging​

Note

If you want to disable all logging, set allowSuppressLogLevel to true in your ADTConfig instance and call the setLogLevel method with the value ADTLogLevelSuppress.

To set the verbosity of logging, use the logLevel property in your ADTConfig instance. You need to do this before calling appDidLaunch for it to take effect.

[adtraceConfig setLogLevel:ADTLogLevelVerbose]; // enable all logging
[adtraceConfig setLogLevel:ADTLogLevelDebug]; // enable more logging
[adtraceConfig setLogLevel:ADTLogLevelInfo]; // the default
[adtraceConfig setLogLevel:ADTLogLevelWarn]; // disable info logging
[adtraceConfig setLogLevel:ADTLogLevelError]; // disable warnings as well
[adtraceConfig setLogLevel:ADTLogLevelAssert]; // disable errors as well
[adtraceConfig setLogLevel:ADTLogLevelSuppress]; // disable all logging

If you don't want your app in production to display any logs coming from the Adtrace SDK, then you should select ADTLogLevelSuppress and in addition to that, initialise ADTConfig object with another constructor where you should enable suppress log level mode:

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

    // ...

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

    [Adtrace appDidLaunch:adtraceConfig];

Build your app​

Well done! You should now be able to build and run your app. Enable logging to check for any issues. You are ready to start attributing your users with the Adtrace SDK.