Help Center

Get started with the iOS SDK

The Adjust 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 Adjust SDK. You can also check out our example apps on GitHub .

Step one: set up your environment

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

Important :

The Adjust 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 'Adjust', '~> 4.33.3'
// Get source directly from GitHub
pod 'Adjust', :git => 'https://github.com/adjust/ios_sdk.git', :tag => '4.33.3'

If you are using web views in your app, add the Adjust Web Bridge by adding the following:

pod 'Adjust/WebBridge', '~> 4.33.3'

Carthage

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

github "adjust/ios_sdk"

Swift package manager

To add the SDK using Swift's package manager:

Click File .
Select Swift Packages .
Select Add Package Dependency .
In the box that appears, enter the SDK's GitHub address.

https://github.com/adjust/ios_sdk

Select the version of the Adjust SDK you want to use in the Version dropdown. Check the releases page for the latest stable version.

Add as framework

You can also choose to integrate the Adjust SDK by adding it to your project as a framework. On the releases page you can find the following archives:

AdjustSdkStatic.framework.zip
AdjustSdkDynamic.framework.zip
AdjustSdkTvDynamic.framework.zip
AdjustSdkTvStatic.framework.zip
AdjustSdkImDynamic.framework.zip
AdjustSdkWebBridgeDynamic.framework.zip

Since the release of iOS 8, Apple has introduced dynamic frameworks (also known as embedded frameworks). If your app is targeting iOS 8 or higher, you can use the Adjust SDK dynamic framework. Choose which framework you want to use – static or dynamic – and add it to your project:

Download the archive from the releases page.
Unzip the archive on your computer.
Copy the .framework folder into your Xcode project.

If you are creating a tvOS app, you can make use of our tvOS framework. You can find this in the AdjustSdkTvStatic.framework.zip and AdjustSdkTvDynamic.framework.zip archives.

If you are creating an iMessage app, you can make use of the IM framework. You can find this in the AdjustSdkImDynamic.framework.zip archive.

If you are using web views in your app, you can make use of the Adjust Web Bridge. You can find this in the AdjustSdkWebBridgeDynamic.framework.zip archive.

Step two: integrate the SDK

Cocoapods

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

Objective-C

Swift

Add the following to your AppDelegate.h file:

#import "Adjust.h"
#import <Adjust/Adjust.h>

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

#import "AdjustBridge.h"

Carthage and framework import

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

Objective-C

Swift

Add the following to your AppDelegate.h file:

#import <AdjustSdk/Adjust.h>

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

#import <AdjustSdkWebBridge/AdjustBridge.h>

If you are are using the Adjust SDK with your tvOS app, add the following to your AppDelegate.h file:

#import <AdjustSdkTv/Adjust.h>

If you are are using the Adjust SDK with your iMessage app, add the following to your AppDelegate.h file:

#import <AdjustSdkIm/Adjust.h>

Step three: add iOS frameworks

The Adjust 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 Adjust SDK.

Framework	Description	Notes
`AdSupport.framework`	This 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.framework`	This framework is needed to handle Apple Search Ads attribution.
`StoreKit.framework`	This framework is needed to access the SKAdNetwork framework and for the Adjust SDK to handle communication with it automatically in iOS 14 or later.
`AppTrackingTransparency.framework`	This 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`	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.

Step four: initialize the SDK

Once you've added all necessary frameworks, you can initialize the Adjust SDK within your application. To do this, initialize your ADJConfig 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


                 ADJEnvironmentSandbox

. Change this to


                 ADJEnvironmentProduction

before you submit your application to the App Store.

Standard setup

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 Adjust in the didFinishLaunching or didFinishLaunchingWithOptions method of your app delegate:

Objective-C

Swift

#import "Adjust.h"
// or #import <Adjust/Adjust.h>
// or #import <AdjustSdk/Adjust.h>
// or #import <AdjustSdkTv/Adjust.h>
// or #import <AdjustSdkIm/Adjust.h>
// ...
NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADJEnvironmentSandbox;
*adjustConfig = [ADJConfig configWithAppToken:yourAppToken
                                  environment:environment];
[Adjust appDidLaunch:adjustConfig];

Important :

Initializing the Adjust SDK like this is important. Initializing the Adjust SDK at any other time can lead to unexpected behavior. See our FAQs for more information.

iMessage setup

Depending on how you have added the Adjust SDK to your project, you will need to do some additional steps:

If you have added the Adjust SDK from source, make sure that you have pre-processor macro ADJUST_IM=1 set in your iMessage project settings.
If you have added the Adjust SDK as a framework, make sure to add New Copy Files Phase in your Build Phases project settings. Set the AdjustSdkIm.framework to be copied to the Frameworks folder.

Session tracking

To set up session tracking in an iMessage app, you need to do an additional step. In a standard iOS app, the Adjust SDK is subscribed to iOS system notifications. This enables the Adjust SDK to know when the app has entered and left the foreground. This is not how iMessage apps work. For this reason, you need to add calls to the trackSubsessionStart and trackSubsessionEnd methods in your app view controller. This will notify the Adjust SDK when your app has entered and left the foreground.

Add a call to trackSubsessionStart inside your didBecomeActiveWithConversation: method:

Objective-C

Swift

-(void)didBecomeActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the inactive to active state.
    // This will happen when the extension is about to present UI.
    // Use this method to configure the extension and restore previously stored state.
    [Adjust trackSubsessionStart];
}

Add a call to trackSubsessionEnd inside your willResignActiveWithConversation:` method:

Objective-C

Swift

-(void)willResignActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the active to inactive state.
    // This will happen when the user dissmises the extension, changes to a different
    // conversation or quits Messages.
    // Use this method to release shared resources, save user data, invalidate timers,
    // and store enough state information to restore your extension to its current state
    // in case it is stopped later.
    [Adjust trackSubsessionEnd];
}

Note :

Apps and iMessage extensions run in different memory spaces. This is because they have different bundle identifiers. Because of this, initializing the Adjust SDK with the same app token in both the app and the extension can cause issues. The two independent instances will track things independently of one another. This can lead to the Adjust SDK returning mixed data to the Adjust backend. You should create a separate app in your Adjust dashboard for your iMessage app, then initialize the Adjust SDK with the new token.

Web bridge setup

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

Integrate `AdjustBridge` 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 AdjustBridge in the viewDidLoad or viewWillAppear method of your Web View Delegate:

Objective-C

Swift

#import "AdjustBridge.h"
// or #import <AdjustSdkWebBridge/AdjustBridge.h>
- (void)viewWillAppear:(BOOL)animated {
    WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds];
    // add @property (nonatomic, strong) AdjustBridge *adjustBridge; on your interface
    [self.adjustBridge loadWKWebViewBridge:webView];
    // optionally you can add a web view delegate so that you can also capture its events
    // [self.adjustBridge 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 AdjustBridge instance. See the library's documentation for usage information.

Integrate `AdjustBridge` 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 Adjust iOS web bridge:

Javascript

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 = AdjustConfig.EnvironmentSandbox;
    var adjustConfig = new AdjustConfig(yourAppToken, environment);
    Adjust.appDidLaunch(adjustConfig);

Get started with the iOS SDK

Step one: set up your environment

Cocoapods

Carthage

Swift package manager

Add as framework

Step two: integrate the SDK

Cocoapods

Carthage and framework import

Step three: add iOS frameworks

Step four: initialize the SDK

Standard setup

iMessage setup

Session tracking

Web bridge setup

Integrate AdjustBridge into your app

Integrate AdjustBridge into your web view

Integrate `AdjustBridge` into your app

Integrate `AdjustBridge` into your web view