Apple Search Ads



Branch can help track your Apple Search Ads campaigns by fetching the Apple Search Ads Attribution API. You can then use the parameters you've set in the Apple Search Ads dashboard, parameters such as the campaign name, and take special action in your app after an install, or simply track the effectiveness of a campaign in the Branch dashboard, along with your other Branch statistics, such as total installs, referrals, and app link statistics.


Apple Search Ads Updated Framework (April 2021)

Apple Search Ads (ASA) integration has been updated. In the old framework, we were unable to get attribution data from users that had limited ad tracking enabled. In the new framework, Apple will return a modified response for users that are opted out of tracking; thus, Branch will receive attribution data from users that have limit ad tracking enabled.

For users that have opted out of tracking, Apple will return an attribution response but it will not contain a 'click time'.

If you are currently using the old ASA framework (SDK or S2S), we recommend upgrading to the latest SDK and run both frameworks in parallel.

Note: The new framework only works for iOS version 14.3+ because a token is only on iOS v14.3+. Apple Search Ads does not use the SKAdNetwork framework.

SDK Set Up (New Framework)

Update the Branch SDK to iOS v1.39.0+. The new SDK will automatically retrieve a token on your behalf, our servers will use that token to call the Apple Search Ads Attribution API.
Note: If you are using Cocoapods, you need to manually import AdServices Framework


AdServices Framework

On SDK v1.39.1+, we recommend you import AdServices Framework to leverage the Apple Ads Attribution API.

SDK Setup (Old Framework)

In order to check if the user came from an Apple Search Ads, you must make the attribution call before Branch initializes. As a warning, Apple's Search Ads Attribution API may take more than 1 second round trip. This means that your call to Branch's initSession to the execution of the callback block may be delayed by this additional 1 second.

Import iAd, AdSupport, and AdServices

You must add Apple's iAd.framework, AdSupport.framework, and AdServices.framework to your Linked Frameworks in your Xcode project to enable Apple Search Ads checking.



Using Cocoapods

If using Cocoapods, the iAd framework is automatically added (in build phase) and the headers are imported. If not using Cocoapods, you will need to do this manually.

Enable Apple Search Ads Check


Branch iOS SDK v0.30.0

As of v0.30.0, the Branch iOS SDK supports new logic that increases wait time for Apple Search Ads to respond with the payload, as well as ignore Apple's test data.

To enable this check, add a delayInitToCheckForSearchAds call to your AppDelegate.m (or AppDelegate.swift) file after you create the Branch singleton, but before you call initSession. Your code will end up looking something like this:


Branch *branch = [Branch getInstance];

// This will usually add less than 1 second on first time startup.  Up to 3.5 seconds if Apple Search Ads fails to respond.
[branch delayInitToCheckForSearchAds];

// Increases the amount of time the SDK waits for Apple Search Ads to respond. The default wait has a better than 90% success rate, however waiting longer can improve the success rate. This will increase the usual delay to about 3 seconds on first time startup.  Up to about 15 seconds if Apple Search Ads fails to respond.
[branch useLongerWaitForAppleSearchAds];

// Branch won't callback with Apple's test data, this is still sent to the server.
[branch ignoreAppleSearchAdsTestData];

[branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
    // handle payload


let branch = Branch.getInstance()

// This will usually add less than 1 second on first time startup.  Up to 3.5 seconds if Apple Search Ads fails to respond.

// Increases the amount of time the SDK waits for Apple Search Ads to respond. The default wait has a better than 90% success rate, however waiting longer can improve the success rate. This will increase the usual delay to about 3 seconds on first time startup.  Up to about 15 seconds if Apple Search Ads fails to respond.

// Branch won't callback with Apple's test data, this is still sent to the server.
branch.initSession(launchOptions: launchOptions, andRegisterDeepLinkHandler: { (params, error) in
    // handle payload


Testing Apple Search Ads

If you test using a non-production app and do not use the ignoreAppleSearchAdsTestData() method, the iAd framework will return fake Apple Search Ads payloads to simulate the install being claimed by Apple Search Ads. Subsequently, you will see these claims in your reporting.


Impact on Deferred Deep Linking

If you use deferred deep linking, do not use the useLongerWaitForAppleSearchAds() method as it will negatively impact the end user's experience by creating longer wait times for the deferred deep linking to occur.

Server to Sever Setup (New Framework)

  • For S2S integrations, you will need to retrieve the new token and send to Branch on the install as apple_attribution_token This is necessary only if you send installs S2S. No need to complete this step in case installs are recorded by Branch iOS SDK.

Please refer to the new AdServices developer documentation on how to retrieve the token.

  1. Import AdServices.framework
  2. Request attribution token (see sample code). This should be available from Apple within 50ms.
  3. The token has a 24 hr TTL, so send to Branch within that time in order to use it for attribution.

See sample code for obtaining the Apple Attribution token:

func appleAttributionToken() -> String? {
        if #available(iOS 14.3, *) {
            return try? AAAttribution.attributionToken()
        return nil
+ (NSString *)appleAttributionToken {
    if (@available(iOS 14.3, *)) {
        NSError *error;
        NSString *appleAttributionToken = [AAAttribution attributionTokenWithError:&error];
        if (!error) {
            return appleAttributionToken;
    return nil;

Server to Server Setup (Old Framework)

If you have a S2S integration with Branch (i.e. you do not use the Branch SDK to send Branch data), you will need to perform the Apple Search Ads check yourself before sending the returned payload to Branch.

Please refer to Apple Search Ads developer documentation on how to make requests to their API.

Implementation Guidelines

  • Give a 2 second buffer before calling Apple's Attribution API. If your request times out after 5 seconds, please retry.
  • Implement retry logic if response returns as False or Error Code [0,2,3]. Call Apple again 2 seconds later.
  • After 20 seconds or successful response, call Branch with the returned Apple Search Ads payload.

Cost Data Setup

  1. Navigate to the partner management tab and search for Apple Search Ads
  2. Click Sign in With Apple
  1. Sign in with your Apple account. Once signed in, accept permissions and select Grant Access
11461146 19581958
  1. On the Branch Dashboard, select the relevant ad accounts
  1. Hit Save


Cost Data Support


Agency-Managed Campaigns

Apple Search Ads Data Mapped to Branch

Branch receives and maps the following parameters from the Apple Search Ads Attribution API:

Old Framework

Apple Search Ads ParameterBranch Mapped Field

New Framework

Apple Search Ads ParameterBranch Mapped Field

Additional Fields Supported

Apple Search Ads ParameterBranch Mapped Field

View Attribution on Dashboard

All the attribution can be visible on the Branch Dashboard summary page. All installs and opens registered from this channel will automatically be tagged with the channel: Apple App Store and the Ad Partner: Apple Search Ads. The campaign will be set to the Campaign Name you've configured in the Apple Search Ads dashboard.

  • Installs might not be accurate, but installs + open events should match what Apple Search Ads reports.
  • Due to API limitations, it may take up to 30 days for full attribution of a device.

Note that these stats are limited to the date range at the top of the page. You can expand the range if you'd like.


Attribution Windows

Attribution windows can be specified at the global account level or on a per link basis with the link level window taking priority.

Please see our guide on Attribution Windows.

Keyword ID

With the new framework, keywordId is also passed to Branch , and you may use that in your Compare Bys to measure your campaign performance.


This is also available in Branch's Query API in the last_attributed_touch_data_tilde_keyword_id field in all EO topics.

Integration Support

Install discrepancies when compared with Apple Search Ads dashboard

There are a few possible causes of discrepancies with Apple Search Ads. Due to the low customizability of Apple Search Ads' attribution settings, discrepancies are often higher on Apple Search Ads than other platforms, even though performance may be solid and reporting may be working as expected. The best way to attempt reconciliation with ASA installs and Branch is to look at 'New Download' counts, but subtract the percentage of LAT on users found by grouping LAT on/off in reporting. This will give an estimate of new downloads with LAT off, while Branch reports first opens from those downloads.

  • Time zones. Ensure your Apple Search Ads time zone (in Settings > Overview > Account Information ) matches your Branch Dashboard time zone (visible under Account Settings).
  • Limit Ad Tracking (LAT) On. Apple Search Ads doesn't report installs to third parties if the user has Limit Ad Tracking enabled via the old framework. However the Apple Search Ads dashboard shows all installs by default, regardless of limit ad tracking state. If the newer framework is properly set up, attribution will still be provided for LAT-on or ATT opted-out users and this will not be a source of discrepancy, but if the new framework is not set up properly this may still cause a difference in numbers.
  • Attribution Windows. Apple Search Ads attributes all installs within 30 days of an Apple Search Ads click to itself. Branch's default click to install attribution window is 7 days. You can modify Branch's click to install window. You can modify your Apple Search Ads attribution windows in Branch.
  • Last-click attribution. Apple Search Ads attributes all installs within 30 days of an Apple Search Ads click to itself. Branch will attribute to the last click within its attribution windows, which can often be a different source than Apple Search Ads.
  • Reinstalls. Apple Search Ads' dashboard shows reinstalls as conversions in its default view, but Branch calls these installs "REINSTALLS." In the Apple dashboard, select New Downloads or Redownloads in the column selector to align data.
  • Attribution API timeouts or delays. Apple Search Ads Attribution API can be slow to respond. Although customers can edit the timeout, the default Branch timeout in the code above is just over 1 second. If Apple Search Ads responds after this timeout, Branch will not attribute the install to Apple Search Ads.
  • Opens vs. installs. Branch considers the first open to be the install. Apple Search Ads considers the time that the user downloaded the app to be an install. This can cause discrepancies in counts and date of install.

Adding deep linking to Apple Search Ads

Since this integration doesn't utilize Branch links, options for deep linking are limited. We'll pass back the value you use for campaign in the Apple Search Ads dashboard. Since this value is controlled by you, you can put anything there, but it will reflect on the Branch dashboard. We will track installs regularly.

Installs or conversion events appearing without keywords in Branch dashboard

There are Keyword and Search Match match sources for Apple Search Ads. The Search Match feature automatically matches your ad to relevant user searches on the App Store, rather than a rubric of preassigned keywords. Installs attributed to Search Matches do not have keywords associated with them. Search Match can be enabled & disabled at the Ad Group level in the Apple Search Ads dashboard.

Using TestFlight app or Developer App

If you are using the new ASA framework and are debugging or testing your app using the TestFlight app or developer app, Apple Search Ads returns dummy values of test campaign data with Campaign ID as 1234567890 which will be visible in the Branch Dashboard. Please ensure to filter it out when looking at your ASA attributed campaign data in the Dashboard.


If you ever need to restart your integration with Apple Search Ads, you must do so by clicking the Reset Settings button in the Apple Search Ads settings in the Branch Dashboard. Clicking the Disable button at the bottom will not reset your integration.


Did this page help you?