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
:
If you’re using web views in your app, add the Adjust Web Bridge by adding the following:
To add the SDK using Carthage, add the following to your Cartfile
:
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
.framework
folder into yourXcode
project.
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:
If you use the Adjust Web Bridge, add the following to your bridging header file:
To import the Adjust SDK, add the following to your AppDelegate.h
file:
If you use the Adjust Web Bridge, add the following to your AppDelegate.h
file:
Add the relevant import statements in your project files:
To import the Adjust SDK, add the following to your bridging header file:
If you use the Adjust Web Bridge, add the following to your bridging header file:
If you use the Adjust SDK in a tvOS app, add the following to your bridging header file:
If you use the Adjust SDK in a iMessage app, add the following to your bridging header file:
To import the Adjust SDK, add the following to your AppDelegate.h
file:
If you use the Adjust Web Bridge, add the following to your AppDelegate.h
file:
If you use the Adjust SDK in your tvOS app, add the following to your AppDelegate.h
file:
If you use the Adjust SDK in your iMessage app, add the following to your AppDelegate.h
file:
Add the relevant import statements in your project files:
To import the Adjust SDK, add the following to your bridging header file:
If you use the Adjust Web Bridge, add the following to your bridging header file:
If you use the Adjust SDK in a tvOS app, add the following to your bridging header file:
If you use the Adjust SDK in a iMessage app, add the following to your bridging header file:
To import the Adjust SDK, add the following to your AppDelegate.h
file:
If you use the Adjust Web Bridge, add the following to your AppDelegate.h
file:
If you use the Adjust SDK in your tvOS app, add the following to your AppDelegate.h
file:
If you use the Adjust SDK in your iMessage app, add the following to your AppDelegate.h
file:
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 later. |
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
didFinishLaunching
ordidFinishLaunchingWithOptions
method of your app delegate. - Set the
logLevel
property on your config object toADJLogLevelVerbose
(verbose). You must enable verbose logging to retrieve device information. - Pass the config object as an argument to the
appDidLaunch
method.
Set up your iMessage app
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=1
pre-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.framework
to 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:
Add a call to trackSubsessionEnd
inside your willResignActiveWithConversation:
method:
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
import
statement at the top of the file. - Add the following calls to
AdjustBridge
in theviewDidLoad
orviewWillAppear
method of your Web View Delegate:
You 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:
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 anallowSuppressLogLevel
argument in your config object.
You can use Xcode
’s build flags to dynamically update your config depending on whether you create a debug build or a production build.