SDK v5 is in open beta. All features are subject to change.
The Adjust iOS SDK enables you to record attribution, events, and more in your iOS app. This guide shows you how to integrate the Adjust SDK with your app.
Before you begin
Here’s what you need to do before updating to SDK v5:
- SDK v5 supports SDK signature verification natively. If you currently use the SDK signature library, you need to uninstall this first.
- If your app targets iOS or tvOS earlier than version 12.0, you need to update your app before you can use SDK v5.
1. Set up your environment
To add the SDK using Cocoapods, specify the version you want to use in your Podfile:
// Get source directly from GitHubpod 'Adjust', :git => 'https://github.com/adjust/ios_sdk.git', :branch => 'v5'2. Integrate the Adjust SDK
Once you’ve added the Adjust SDK to your Xcode project, you need to integrate it in your app.
Add the relevant import statements in your project files.
To import the Adjust SDK, add the following to your bridging header file:
#import AdjustSdkTo import the Adjust SDK, add the following to your AppDelegate.h file:
#import <AdjustSdk/Adjust.h>3. Add iOS frameworks
The Adjust SDK depends on frameworks to access certain device information. To enable reading this information, add the frameworks and mark them as optional.
| Framework | Description | Notes |
|---|---|---|
AdSupport.framework | Enables access to the device’s IDFA. Also enables access to LAT information on devices running iOS 14 or earlier. | Don’t add this framework if your app targets the “Kids” category. |
AdServices.framework | Handles ASA attribution. | |
StoreKit.framework | Enables access to the SKAdNetwork framework. | Required to allow the Adjust SDK to handle communication with SKAdNetwork on devices running iOS 14 or earlier. |
AppTrackingTransparency.framework | Required to allow the Adjust SDK to wrap user ATT consent dialog and access consent responses on devices running iOS 14 or later | Don’t add this framework if your app targets the “Kids” category |
WebKit.framework | Enables the use of web views in your application | Only required if your app uses web views |
4. Initialize the Adjust SDK
To initialize the Adjust SDK, you need to create a config object. This object contains configuration options that control how the Adjust SDK behaves. Pass the following arguments for a minimal setup:
appToken: Your app’s token.environment: The environment you want to run the SDK in. Set this toADJEnvironmentSandbox.
To initialize the Adjust SDK with this config object:
- Declare your config object in the
didFinishLaunchingordidFinishLaunchingWithOptionsmethod of your app delegate. - Set the
logLevelproperty on your config object toADJLogLevelVerbose(verbose). You must enable verbose logging to retrieve device information. - Pass the config object as an argument to the
initSdkmethod.
import AdjustSdk
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Override point for customization after application launch. let yourAppToken = "{YourAppToken}" let environment = ADJEnvironmentSandbox let adjustConfig = ADJConfig(appToken: yourAppToken, andEnvironment: environment)
Adjust.initSdk(adjustConfig) //... return true }#import <AdjustSdk/Adjust.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}"; NSString *environment = ADJEnvironmentSandbox; ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken andEnvironment:environment]; // Your code here [Adjust initSdk:myAdjustConfig]; // Your code here return YES;}Set up your iMessage app
iMessage extensions have different bundle identifiers to apps and run in a different memory space. If you configure both with the same token, the SDK returns mixed data. You must create a separate app in the Adjust dashboard for your iMessage app and use its token when initializing the Adjust SDK.
If your app targets iMessage, there are some additional settings you must configure:
- If you added the Adjust SDK from source, add the
ADJUST_IM=1pre-processor macro to your iMessage project settings. - If you added the Adjust SDK as a framework, make sure to add New Copy Files Phase in your Build Phases project settings. Set the
AdjustSdkIm.frameworkto be copied to the Frameworks folder.
Record sessions
The Adjust SDK isn’t subscribed to iOS system notifications in iMessage apps. To notify the Adjust SDK when your app has entered or left the foreground, you need to call the trackSubsessionStart and trackSubsessionEnd methods.
Add a call to trackSubsessionStart inside your didBecomeActiveWithConversation: method:
func didBecomeActive(with conversation: MSConversation) { // 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()}-(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:
func willResignActive(with conversation: MSConversation) { // Called when the extension is about to move from the active to inactive state. // This will happen when the user dismisses 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 terminated later.
Adjust.trackSubsessionEnd()}-(void)willResignActiveWithConversation:(MSConversation *)conversation { // Called when the extension is about to move from the active to inactive state. // This will happen when the user dismisses 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 terminated later.
[Adjust trackSubsessionEnd];}5. Configure the Adjust SDK
Once you’ve added your config object and initialization logic, you can configure the Adjust SDK to record information about different parts of your app. Check out the configuration reference and feature guides to set up exactly what you want to record.
6. Test the Adjust SDK
Now that you’ve configured the Adjust SDK to record information about your app, it’s time to test it. Adjust offers a testing console and a Device API to help you test your app.
Follow the testing guide to make sure Adjust receives the expected values back from your app.
7. Build your app for production
Once you’ve finished your testing, you can build your app for production. To do this, you need to update your config object.
Update the following values:
environment: Set this toADJEnvironmentProduction.logLevel: Choose a logging level, or disable logging completely by passing anallowSuppressLogLevelargument in your config object.
import AdjustSdk
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Override point for customization after application launch. let yourAppToken = "{YourAppToken}" let environment = ADJEnvironmentProduction let adjustConfig = ADJConfig( appToken: yourAppToken, environment: environment, andSuppressLogLevel: true) adjustConfig?.logLevel = ADJLogLevelVerbose //... Adjust.initSdk(adjustConfig) //... return true}#import <AdjustSdk/Adjust.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}"; NSString *environment = ADJEnvironmentSandbox; ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken andEnvironment:environment]; [adjustConfig setLogLevel:ADJLogLevelVerbose]; //... [Adjust initSdk:adjustConfig]; //... return YES;}You can use Xcode’s build flags to dynamically update your config depending on whether you create a debug build or a production build.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Override point for customization after application launch. let yourAppToken = "{YourAppToken}"
#if DEBUG let environment = ADJEnvironmentSandbox let adjustConfig = ADJConfig( appToken: yourAppToken, andEnvironment: environment) adjustConfig?.logLevel = ADJLogLevelVerbose
#else let environment = ADJEnvironmentProduction let adjustConfig = ADJConfig( appToken: yourAppToken, andEnvironment: environment) adjustConfig?.logLevel = ADJLogLevelSuppress #endif //... Adjust.initSdk(adjustConfig) //... return true}#import "Adjust.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}";
#if DEBUG NSString *environment = ADJEnvironmentSandbox; ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken andEnvironment:environment]; [adjustConfig setLogLevel:ADJLogLevelVerbose];
#else NSString *environment = ADJEnvironmentProduction; ADJConfig *adjustConfig = [[ADJConfig alloc] initWithAppToken:appToken andEnvironment:environment]; [adjustConfig setLogLevel:ADJLogLevelSuppress]; #endif //... [Adjust initSdk: adjustConfig]; //... return YES;}The Adjust iOS SDK enables you to record attribution, events, and more in your iOS app. This guide shows you how to integrate the Adjust SDK with your app.
1. Add the SDK to your project
To use the Adjust SDK in your iOS app, you need to add it to your Xcode project.
To add the SDK using Swift’s package manager:
- Select File —> Swift Packages —> 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 version.
Alternative installation methods
To add the SDK using Cocoapods, specify the version you want to use in your Podfile:
// Get pod from repositorypod 'Adjust', '~> 4.38.4'
// Get source directly from GitHubpod 'Adjust', :git => 'https://github.com/adjust/ios_sdk.git', :tag => 'v4.38.4'If you’re using web views in your app, add the Adjust Web Bridge by adding the following:
pod 'Adjust/WebBridge', '~> 4.38.4'To add the SDK using Carthage, add the following to your Cartfile:
github "adjust/ios_sdk"The distribution of static frameworks is deprecated from version 4.38.0, as a result of not including the Privacy Manifest.
You can integrate the Adjust SDK by adding it to your project as a framework. You can find the following archives on the releases page:
AdjustSdkStatic.framework.zip: For devices running iOS 7 and belowAdjustSdkDynamic.framework.zip: For devices running iOS 8 and aboveAdjustSdkTvDynamic.framework.zip: Dynamic framework for tvOS appsAdjustSdkTvStatic.framework.zip: Static framework for tvOS appsAdjustSdkImDynamic.framework.zip: Dynamic framework for iMessage appsAdjustSdkWebBridgeDynamic.framework.zip: Dynamic framework for web views
Choose the frameworks you need and add them to your Xcode project:
- Download the archive from the releases page.
- Unzip the archive on your computer.
- Copy the
.frameworkfolder into yourXcodeproject.
2. Integrate the Adjust SDK
Once you’ve added the Adjust SDK to your Xcode project, you need to integrate it in your app.
Add the relevant import statements in your project files.
To import the Adjust SDK, add the following to your bridging header file:
#import <Adjust/Adjust.h>If you use the Adjust Web Bridge, add the following to your bridging header file:
#import "AdjustBridge.h"To import the Adjust SDK, add the following to your AppDelegate.h file:
#import <Adjust/Adjust.h>If you use the Adjust Web Bridge, add the following to your AppDelegate.h file:
#import "AdjustBridge.h"Add the relevant import statements in your project files:
To import the Adjust SDK, add the following to your bridging header file:
#import <Adjust/Adjust.h>If you use the Adjust Web Bridge, add the following to your bridging header file:
#import <AdjustSdkWebBridge/AdjustBridge.h>If you use the Adjust SDK in a tvOS app, add the following to your bridging header file:
#import <AdjustSdkTv/Adjust.h>If you use the Adjust SDK in a iMessage app, add the following to your bridging header file:
#import <AdjustSdkIm/Adjust.h>To import the Adjust SDK, add the following to your AppDelegate.h file:
#import <AdjustSdk/Adjust.h>If you use the Adjust Web Bridge, add the following to your AppDelegate.h file:
#import <AdjustSdkWebBridge/AdjustBridge.h>If you use the Adjust SDK in your tvOS app, add the following to your AppDelegate.h file:
#import <AdjustSdkTv/Adjust.h>If you use the Adjust SDK in your iMessage app, add the following to your AppDelegate.h file:
#import <AdjustSdkIm/Adjust.h>Add the relevant import statements in your project files:
To import the Adjust SDK, add the following to your bridging header file:
#import <Adjust/Adjust.h>If you use the Adjust Web Bridge, add the following to your bridging header file:
#import <AdjustSdkWebBridge/AdjustBridge.h>If you use the Adjust SDK in a tvOS app, add the following to your bridging header file:
#import <AdjustSdkTv/Adjust.h>If you use the Adjust SDK in a iMessage app, add the following to your bridging header file:
#import <AdjustSdkIm/Adjust.h>To import the Adjust SDK, add the following to your AppDelegate.h file:
#import <AdjustSdk/Adjust.h>If you use the Adjust Web Bridge, add the following to your AppDelegate.h file:
#import <AdjustSdkWebBridge/AdjustBridge.h>If you use the Adjust SDK in your tvOS app, add the following to your AppDelegate.h file:
#import <AdjustSdkTv/Adjust.h>If you use the Adjust SDK in your iMessage app, add the following to your AppDelegate.h file:
#import <AdjustSdkIm/Adjust.h>3. Add iOS frameworks
The Adjust SDK depends on frameworks to access certain device information. To enable reading this information, add the frameworks and mark them as optional.
| Framework | Description | Notes |
|---|---|---|
AdSupport.framework | Enables access to the device’s IDFA. Also enables access to LAT information on devices running iOS 14 or earlier. | Don’t add this framework if your app targets the “Kids” category. |
AdServices.framework | Handles ASA attribution. | |
StoreKit.framework | Enables access to the SKAdNetwork framework. | Required to allow the Adjust SDK to handle communication with SKAdNetwork on devices running iOS 14 or earlier. |
AppTrackingTransparency.framework | Required to allow the Adjust SDK to wrap user ATT consent dialog and access consent responses on devices running iOS 14 or later | Don’t add this framework if your app targets the “Kids” category |
WebKit.framework | Enables the use of web views in your application | Only required if your app uses web views |
4. Initialize the Adjust SDK
To initialize the Adjust SDK, you need to create a config object. This object contains configuration options that control how the Adjust SDK behaves. Pass the following arguments for a minimal setup:
appToken: Your app’s token.environment: The environment you want to run the SDK in. Set this toADJEnvironmentSandbox.
To initialize the Adjust SDK with this config object:
- Declare your config object in the
didFinishLaunchingordidFinishLaunchingWithOptionsmethod of your app delegate. - Set the
logLevelproperty on your config object toADJLogLevelVerbose(verbose). You must enable verbose logging to retrieve device information. - Pass the config object as an argument to the
appDidLaunchmethod.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let yourAppToken = "{YourAppToken}" let environment = ADJEnvironmentSandbox as? String let myAdjustConfig = ADJConfig( appToken: yourAppToken, environment: environment) myAdjustConfig?.logLevel = ADJLogLevelVerbose // Your code here Adjust.appDidLaunch(myAdjustConfig) // Your code here return true}#import "Adjust.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}"; NSString *environment = ADJEnvironmentSandbox; *myAdjustConfig = [ADJConfig configWithAppToken:yourAppToken environment:environment]; [myAdjustConfig setLogLevel:ADJLogLevelVerbose]; // Your code here [Adjust appDidLaunch:myAdjustConfig]; // Your code here return YES;}Set up your iMessage app
iMessage extensions have different bundle identifiers to apps and run in a different memory space. If you configure both with the same token, the SDK returns mixed data. You must create a separate app in the Adjust dashboard for your iMessage app and use its token when initializing the Adjust SDK.
If your app targets iMessage, there are some additional settings you must configure:
- If you added the Adjust SDK from source, add the
ADJUST_IM=1pre-processor macro to your iMessage project settings. - If you added the Adjust SDK as a framework, make sure to add New Copy Files Phase in your Build Phases project settings. Set the
AdjustSdkIm.frameworkto be copied to the Frameworks folder.
Record sessions
The Adjust SDK isn’t subscribed to iOS system notifications in iMessage apps. To notify the Adjust SDK when your app has entered or left the foreground, you need to call the trackSubsessionStart and trackSubsessionEnd methods.
Add a call to trackSubsessionStart inside your didBecomeActiveWithConversation: method:
func didBecomeActive(with conversation: MSConversation) { // 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()}-(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:
func willResignActive(with conversation: MSConversation) { // Called when the extension is about to move from the active to inactive state. // This will happen when the user dismisses 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 terminated later.
Adjust.trackSubsessionEnd()}-(void)willResignActiveWithConversation:(MSConversation *)conversation { // Called when the extension is about to move from the active to inactive state. // This will happen when the user dismisses 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 terminated later.
[Adjust trackSubsessionEnd];}Set up the Adjust Web Bridge
If your app uses web views, you must set up the Adjust Web Bridge to record activity inside the web view.
Integrate AdjustBridge into your app
In the Project Navigator:
- Open the source file of your View Controller.
- Add the
importstatement at the top of the file. - Add the following calls to
AdjustBridgein theviewDidLoadorviewWillAppearmethod of your Web View Delegate:
func viewWillAppear(_ animated: Bool) { let webView = WKWebView(frame: view.bounds)
// add var adjustBridge: AdjustBridge? on your interface adjustBridge.loadWKWebViewBridge(webView) // optionally you can add a web view delegate so that you can also capture its events // adjustBridge.loadWKWebViewBridge(webView, wkWebViewDelegate: self as? WKNavigationDelegate?);}#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];}
// Your code hereYou can also use the included WebViewJavascriptBridge 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. Add the following Javascript code to initialize the Adjust 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) { // Your code here var yourAppToken = yourAppToken; var environment = AdjustConfig.EnvironmentSandbox; var adjustConfig = new AdjustConfig(yourAppToken, environment); Adjust.appDidLaunch(adjustConfig); // Your code here});5. Configure the Adjust SDK
Once you’ve added your config object and initialization logic, you can configure the Adjust SDK to record information about different parts of your app. Check out the guides for the SDK’s configuration features and recording features to set up exactly what you want to record.
6. Test the Adjust SDK
Now that you’ve configured the Adjust SDK to record information about your app, it’s time to test it. Adjust offers a testing console and a Device API to help you test your app.
Follow the testing guide to make sure Adjust receives the expected values back from your app.
7. Build your app for production
Once you’ve finished your testing, you can build your app for production. To do this, you need to update your config object.
Update the following values:
environment: Set this toADJEnvironmentProduction.logLevel: Choose a logging level, or disable logging completely by passing anallowSuppressLogLevelargument in your config object.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let yourAppToken = "{YourAppToken}" let environment = ADJEnvironmentProduction as? String let myAdjustConfig = ADJConfig( appToken: yourAppToken, environment: environment, allowSuppressLogLevel: true) myAdjustConfig?.logLevel = ADJLogLevelSuppress //... Adjust.appDidLaunch(myAdjustConfig) //... return true}#import "Adjust.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}"; NSString *environment = ADJEnvironmentProduction; *myAdjustConfig = [ADJConfig configWithAppToken:yourAppToken environment:environment allowSuppressLogLevel:YES]; [myAdjustConfig setLogLevel:ADJLogLevelSuppress]; //... [Adjust appDidLaunch:myAdjustConfig]; //... return YES;}You can use Xcode’s build flags to dynamically update your config depending on whether you create a debug build or a production build.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let yourAppToken = "{YourAppToken}"
#if DEBUG let environment = ADJEnvironmentSandbox as? String let myAdjustConfig = ADJConfig( appToken: yourAppToken, environment: environment) myAdjustConfig?.logLevel = ADJLogLevelVerbose
#else let environment = ADJEnvironmentProduction as? String let myAdjustConfig = ADJConfig( appToken: yourAppToken, environment: environment, allowSuppressLogLevel: true) myAdjustConfig?.logLevel = ADJLogLevelSuppress #endif //... Adjust.appDidLaunch(myAdjustConfig) //... return true}#import "Adjust.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString *yourAppToken = @"{YourAppToken}";
#if DEBUG NSString *environment = ADJEnvironmentSandbox; *myAdjustConfig = [ADJConfig configWithAppToken:yourAppToken environment:environment]; [myAdjustConfig setLogLevel:ADJLogLevelVerbose];
#else NSString *environment = ADJEnvironmentProduction; *myAdjustConfig = [ADJConfig configWithAppToken:yourAppToken environment:environment allowSuppressLogLevel:YES]; [myAdjustConfig setLogLevel:ADJLogLevelSuppress]; #endif //... [Adjust appDidLaunch:myAdjustConfig]; //... return YES;}