开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

This guide is being retired.

This README file will be retired shortly. The SDK documentation can now be found on our help center:

• English
• 中文
• 日本語
• 한국어

Summary

This is the iOS SDK of Adjust™. You can read more about Adjust™ at adjust.com.

If your app is an app which uses web views you would like to use adjust tracking from Javascript code, please consult our iOS web views SDK guide.

Read this in other languages: English, 中文, 日本語, 한국어.

Table of contents

• Example apps
• Basic integration
  • Add the SDK to your project
  • Add iOS frameworks
  • Integrate the SDK into your app
  • Basic setup
    • iMessage specific setup
  • Adjust logging
  • Build your app
• Additional features
  • AppTrackingTransparency framework
    • App-tracking authorisation wrapper
    • Get current authorisation status
    • Check for ATT status change
  • SKAdNetwork framework
    • Update SKAdNetwork conversion value
    • Conversion value updated callback
  • Event tracking
    • Revenue tracking
    • Revenue deduplication
    • Callback parameters
    • Partner parameters
    • Callback identifier
  • Session parameters
    • Session callback parameters
    • Session partner parameters
    • Delay start
  • Attribution callback
  • Ad revenue tracking
  • Subscription tracking
  • Event and session callbacks
  • Disable tracking
  • Offline mode
  • Event buffering
  • GDPR right to be forgotten
  • Third-party sharing
    • Disable third-party sharing
    • Enable third-party sharing
  • Consent measurement
  • SDK signature
  • Background tracking
  • Device IDs
    • iOS Advertising Identifier
    • Adjust device identifier
  • User attribution
  • Push token
  • Pre-installed trackers
  • Deep linking
    • Standard deep linking scenario
    • Deep linking on iOS 8 and earlier
    • Deep linking on iOS 9 and later
    • Deferred deep linking scenario
    • Reattribution via deep links
    • Link resolution
  • Data residency
  • COPPA compliance
• Troubleshooting
  • Issues with delayed SDK initialisation
  • I'm seeing "Adjust requires ARC" error
  • I'm seeing "[UIDevice adjTrackingEnabled]: unrecognized selector sent to instance" error
  • I'm seeing the "Session failed (Ignoring too frequent session.)" error
  • I'm not seeing "Install tracked" in the logs
  • I'm seeing "Unattributable SDK click ignored" message
  • I'm seeing wrong revenue data in the adjust dashboard
• License

Example apps

There are example apps inside the examples directory for iOS (Objective-C), iOS (Swift), tvOS, iMessage and Apple Watch. You can open any of these Xcode projects to see an example of how the Adjust SDK can be integrated.

Basic integration

Add the SDK to your project

If you're using CocoaPods, you can add the following line to your Podfile and continue from this step:

pod 'Adjust', '~> 4.30.0'

or:

pod 'Adjust', :git => 'https://github.com/adjust/ios_sdk.git', :tag => 'v4.30.0'

If you're using Carthage, you can add following line to your Cartfile and continue from this step:

github "adjust/ios_sdk"

If you're using Swift Package Manager, you can add the repository address directly in Xcode going to File > Swift Packages > Add Package Dependency and continue from this step:

https://github.com/adjust/ios_sdk

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
• AdjustSdkTv.framework.zip
• AdjustSdkIm.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.

If you are having tvOS app, you can use the Adjust SDK with it as well with usage of our tvOS framework which you can extract from AdjustSdkTv.framework.zip archive.

If you are having iMessage app, you can use the Adjust SDK with it as well with usage of our IM framework which you can extract from AdjustSdkIm.framework.zip archive.

Add iOS frameworks

Adjust SDK is able to get additional information in case you link additional iOS frameworks to your app. Please, add following frameworks in case you want to enable Adjust SDK features based on their presence in your app and mark them as optional:

• AdSupport.framework - This framework is needed so that SDK can access to IDFA value and (prior to iOS 14) LAT information.
• iAd.framework - This framework is needed so that SDK can automatically handle attribution for ASA campaigns you might be running.
• AdServices.framework - For devices running iOS 14.3 or higher, this framework allows the SDK to automatically handle attribution for ASA campaigns. It is required when leveraging the Apple Ads Attribution API.
• CoreTelephony.framework - This framework is needed so that SDK can determine current radio access technology.
• StoreKit.framework - This framework is needed for access to SKAdNetwork framework and for 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 SDK to be able to wrap user's tracking consent dialog and access to value of the user's consent to be tracked or not.

Integrate the SDK into your app

If you added the Adjust SDK via a Pod repository, you should use one of the following import statements:

#import "Adjust.h"

or

#import <Adjust/Adjust.h>

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

#import <AdjustSdk/Adjust.h>

If you are are using the Adjust SDK with your tvOS app, you should use the following import statement:

#import <AdjustSdkTv/Adjust.h>

If you are are using the Adjust SDK with your iMessage app, you should use the following import statement:

#import <AdjustSdkIm/Adjust.h>

Next, we'll set up basic session tracking.

Basic setup

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

#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;
ADJConfig *adjustConfig = [ADJConfig configWithAppToken:yourAppToken
                                            environment:environment];

[Adjust appDidLaunch:adjustConfig];

Note: Initialising the Adjust SDK like this is very important. Otherwise, you may encounter different kinds of issues as described in our troubleshooting section.

Replace {YourAppToken} with your app token. You can find this in your dashboard.

Depending on whether you build your app for testing or for production, you must set environment with one of these values:

NSString *environment = ADJEnvironmentSandbox;
NSString *environment = ADJEnvironmentProduction;

Important: This value should be set to ADJEnvironmentSandbox if and only if you or someone else is testing your app. Make sure to set the environment to ADJEnvironmentProduction just before you publish the app. Set it back to ADJEnvironmentSandbox when you start developing and testing it again.

We use this environment to distinguish between real traffic and test traffic from test devices. It is very important that you keep this value meaningful at all times! This is especially important if you are tracking revenue.

iMessage specific setup

Adding SDK from source: In case that you have chosen to add Adjust SDK to your iMessage app from source, please make sure that you have pre-processor macro ADJUST_IM=1 set in your iMessage project settings.

Adding SDK as framework: After you have added AdjustSdkIm.framework to your iMessage app, please make sure to add New Copy Files Phase in your Build Phases project settings and select that AdjustSdkIm.framework should be copied to Frameworks folder.

Session tracking: If you would like to have session tracking properly working in your iMessage app, you will need to do one additional integration step. In standard iOS apps Adjust SDK is automatically subscribed to iOS system notifications which enable us to know when app entered or left foreground. In case of iMessage app, this is not the case, so we need you to add explicit calls to trackSubsessionStart and trackSubsessionEnd methods inside of your iMessage app view controller to make our SDK aware of the moments when your app is being in foreground or not.

Add call to trackSubsessionStart inside of didBecomeActiveWithConversation: method:

-(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 call to trackSubsessionEnd inside of willResignActiveWithConversation: method:

-(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 terminated later.

    [Adjust trackSubsessionEnd];
}

With this set, Adjust SDK will be able to successfully perform session tracking inside of your iMessage app.

Note: You should be aware that your iOS app and iMessage extension you wrote for it are running in different memory spaces and they as well have different bundle identifiers. Initialising Adjust SDK with same app token in both places will result in two independent instances tracking things unaware of each other which might cause data mixture you don't want to see in your dashboard data. General advice would be to create separate app in Adjust dashboard for your iMessage app and initialise SDK inside of it with separate app token.

Adjust logging

You can increase or decrease the amount of logs that you see during testing by calling setLogLevel: on your ADJConfig instance with one of the following parameters:

[adjustConfig setLogLevel:ADJLogLevelVerbose];  // enable all logging
[adjustConfig setLogLevel:ADJLogLevelDebug];    // enable more logging
[adjustConfig setLogLevel:ADJLogLevelInfo];     // the default
[adjustConfig setLogLevel:ADJLogLevelWarn];     // disable info logging
[adjustConfig setLogLevel:ADJLogLevelError];    // disable warnings as well
[adjustConfig setLogLevel:ADJLogLevelAssert];   // disable errors as well
[adjustConfig setLogLevel:ADJLogLevelSuppress]; // disable all logging

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

#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;
ADJConfig *adjustConfig = [ADJConfig configWithAppToken:yourAppToken
                                            environment:environment
                                   allowSuppressLogLevel:YES];

[Adjust appDidLaunch:adjustConfig];

Build your app

Build and run your app. If the build succeeds, you should carefully read the SDK logs in the console. After the app launches for the first time, you should see the info log Install tracked.

Additional features

AppTrackingTransparency framework

For each package sent, the Adjust backend receives one of the following four (4) states of consent for access to app-related data that can be used for tracking the user or the device:

• Authorized
• Denied
• Not Determined
• Restricted

After a device receives an authorization request to approve access to app-related data, which is used for user device tracking, the returned status will either be Authorized or Denied.

Before a device receives an authorization request for access to app-related data, which is used for tracking the user or device, the returned status will be Not Determined.

If authorization to use app tracking data is restricted, the returned status will be Restricted.

The SDK has a built-in mechanism to receive an updated status after a user responds to the pop-up dialog, in case you don't want to customize your displayed dialog pop-up. To conveniently and efficiently communicate the new state of consent to the backend, Adjust SDK offers a wrapper around the app tracking authorization method described in the following chapter, App-tracking authorization wrapper.

App-tracking authorisation wrapper

Adjust SDK offers the possibility to use it for requesting user authorization in accessing their app-related data. Adjust SDK has a wrapper built on top of the requestTrackingAuthorizationWithCompletionHandler: method, where you can as well define the callback method to get information about a user's choice. Also, with the use of this wrapper, as soon as a user responds to the pop-up dialog, it's then communicated back using your callback method. The SDK will also inform the backend of the user's choice. The NSUInteger value will be delivered via your callback method with the following meaning:

• 0: ATTrackingManagerAuthorizationStatusNotDetermined
• 1: ATTrackingManagerAuthorizationStatusRestricted
• 2: ATTrackingManagerAuthorizationStatusDenied
• 3: ATTrackingManagerAuthorizationStatusAuthorized

To use this wrapper, you can call it as such:

[Adjust requestTrackingAuthorizationWithCompletionHandler:^(NSUInteger status) {
    switch (status) {
        case 0:
            // ATTrackingManagerAuthorizationStatusNotDetermined case
            break;
        case 1:
            // ATTrackingManagerAuthorizationStatusRestricted case
            break;
        case 2:
            // ATTrackingManagerAuthorizationStatusDenied case
            break;
        case 3:
            // ATTrackingManagerAuthorizationStatusAuthorized case
            break;
    }
}];

Get current authorisation status

To get the current app tracking authorization status you can call [Adjust appTrackingAuthorizationStatus] that will return one of the following possibilities:

• 0: The user hasn't been asked yet
• 1: The user device is restricted
• 2: The user denied access to IDFA
• 3: The user authorized access to IDFA
• -1: The status is not available

Check for ATT status change

In cases where you are not using Adjust app-tracking authorization wrapper, Adjust SDK will not be able to know immediately upon answering the dialog what is the new value of app-tracking status. In situations like this, if you would want Adjust SDK to read the new app-tracking status value and communicate it to our backend, make sure to make a call to this method:

[Adjust checkForNewAttStatus];

SKAdNetwork framework

If you have implemented the Adjust iOS SDK v4.23.0 or above and your app is running on iOS 14, the communication with SKAdNetwork will be set on by default, although you can choose to turn it off. When set on, Adjust automatically registers for SKAdNetwork attribution when the SDK is initialized. If events are set up in the Adjust dashboard to receive conversion values, the Adjust backend sends the conversion value data to the SDK. The SDK then sets the conversion value. After Adjust receives the SKAdNetwork callback data, it is then displayed in the dashboard.

In case you don't want the Adjust SDK to automatically communicate with SKAdNetwork, you can disable that by calling the following method on configuration object:

[adjustConfig deactivateSKAdNetworkHandling];

Update SKAdNetwork conversion value

As of iOS SDK v4.26.0 you can use Adjust SDK wrapper method updateConversionValue: to update SKAdNetwork conversion value for your user:

[Adjust updateConversionValue:6];

Conversion value updated callback

You can register callback to get notified each time when Adjust SDK updates conversion value for the user. You need to implement AdjustDelegate protocol, implement optional adjustConversionValueUpdated: method:

- (void)adjustConversionValueUpdated:(NSNumber *)conversionValue {
    NSLog(@"Conversion value updated callback called!");
    NSLog(@"Conversion value: %@", conversionValue);
}

Event tracking

You can use adjust to track events. Lets say you want to track every tap on a particular button. You would create a new event token in your dashboard, which has an associated event token - looking something like abc123. In your button's buttonDown method you would then add the following lines to track the tap:

ADJEvent *event = [ADJEvent eventWithEventToken:@"abc123"];
[Adjust trackEvent:event];

When tapping the button you should now see Event tracked in the logs.

The event instance can be used to configure the event further before tracking it:

Revenue tracking

If your users can generate revenue by tapping on advertisements or making in-app purchases you can track those revenues with events. Lets say a tap is worth one Euro cent. You could then track the revenue event like this:

ADJEvent *event = [ADJEvent eventWithEventToken:@"abc123"];

[event setRevenue:0.01 currency:@"EUR"];

[Adjust trackEvent:event];

This can be combined with callback parameters of course.

When you set a currency token, adjust will automatically convert the incoming revenues into a reporting revenue of your choice. Read more about currency conversion here.

You can read more about revenue and event tracking in the event tracking guide.

Revenue deduplication

You can also pass in an optional transaction ID to avoid tracking duplicate revenues. The last ten transaction IDs are remembered and revenue events with duplicate transaction IDs are skipped. This is especially useful for in-app purchase tracking. See an example below.

If you want to track in-app purchases, please make sure to call trackEvent after finishTransaction in paymentQueue:updatedTransactions only if the state changed to SKPaymentTransactionStatePurchased. That way you can avoid tracking revenue that is not actually being generated.

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
    for (SKPaymentTransaction *transaction in transactions) {
        switch (transaction.transactionState) {
            case SKPaymentTransactionStatePurchased:
                [self finishTransaction:transaction];

                ADJEvent *event = [ADJEvent eventWithEventToken:...];
                [event setRevenue:... currency:...];
                [event setTransactionId:transaction.transactionIdentifier]; // avoid duplicates
                [Adjust trackEvent:event];

                break;
            // more cases
        }
    }
}

Callback parameters

You can register a callback URL for your events in your dashboard. We will send a GET request to that URL whenever the event is tracked. You can add callback parameters to that event by calling addCallbackParameter to the event before tracking it. We will then append these parameters to your callback URL.

For example, suppose you have registered the URL http://www.mydomain.com/callback then track an event like this:

ADJEvent *event = [ADJEvent eventWithEventToken:@"abc123"];

[event addCallbackParameter:@"key" value:@"value"];
[event addCallbackParameter:@"foo" value:@"bar"];

[Adjust trackEvent:event];

In that case we would track the event and send a request to:

http://www.mydomain.com/callback?key=value&foo=bar

It should be mentioned that we support a variety of placeholders like {idfa} that can be used as parameter values. In the resulting callback this placeholder would be replaced with the ID for Advertisers of the current device. Also note that we don't store any of your custom parameters, but only append them to your callbacks, thus without a callback they will not be saved nor sent to you.

You can read more about using URL callbacks, including a full list of available values, in our callbacks guide.

Partner parameters

You can also add parameters to be transmitted to network partners, which have been activated in your Adjust dashboard.

This works similarly to the callback parameters mentioned above, but can be added by calling the addPartnerParameter method on your ADJEvent instance.

ADJEvent *event = [ADJEvent eventWithEventToken:@"abc123"];

[event addPartnerParameter:@"key" value:@"value"];
[event addPartnerParameter:@"foo" value:@"bar"];

[Adjust trackEvent:event];

You can read more about special partners and these integrations in our guide to special partners.

Callback identifier

You can also add custom string identifier to each event you want to track. This identifier will later be reported in event success and/or event failure callbacks to enable you to keep track on which event was successfully tracked or not. You can set this identifier by calling the setCallbackId method on your ADJEvent instance:

ADJEvent *event = [ADJEvent eventWithEventToken:@"abc123"];

[event setCallbackId:@"Your-Custom-Id"];

[Adjust trackEvent:event];

Session parameters

Some parameters are saved to be sent in every event and session of the Adjust SDK. Once you have added any of these parameters, you don't need to add them every time, since they will be saved locally. If yo