adjust-icon

iOS SDK integration guide

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:

  1. Select File --> Swift Packages --> Add Package Dependency
  2. In the box that appears, enter the SDK's GitHub address: https://github.com/adjust/ios_sdk
  3. 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

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.

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.

FrameworkDescriptionNotes
AdSupport.frameworkEnables 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.frameworkHandles ASA attribution.
StoreKit.frameworkEnables access to the SKAdNetwork framework.Required to allow the Adjust SDK to handle communication with SKAdNetwork on devices running iOS 14 or later.
AppTrackingTransparency.frameworkRequired to allow the Adjust SDK to wrap user ATT consent dialog and access consent responses on devices running iOS 14 or laterDon't add this framework if your app targets the "Kids" category
WebKit.frameworkEnables the use of web views in your applicationOnly required if your app uses web views

4. Set up SDK signature

If you want to use the SDK signature library to secure communications between the Adjust SDK and Adjust's servers, follow the instructions in the SDK signature guide on the Adjust Help Center.

5. (Optional) 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:

  1. Open the source file of your View Controller.
  2. Add the import statement at the top of the file.
  3. Add the following calls to AdjustBridge in the viewDidLoad or viewWillAppear method of your Web View Delegate:

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:

6. 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 to ADJEnvironmentSandbox.

To initialize the Adjust SDK with this config object:

  1. Declare your config object in the didFinishLaunching or didFinishLaunchingWithOptions method of your app delegate.
  2. Set the logLevel property on your config object to ADJLogLevelVerbose (verbose). You must enable verbose logging to retrieve device information.
  3. Pass the config object as an argument to the initSdk 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:

7. 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.

8. 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.

9. 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 to ADJEnvironmentProduction.
  • logLevel: Choose a logging level, or disable logging completely by passing an allowSuppressLogLevel 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.