Prerequisites
To enable Apple Ads, you first need to:
Create a Branch Dashboard.
Enable Ads for your Branch account. Contact your Branch account manager or visit https://branch.io/pricing.
Have a mobile developer prepared to implement the Apple Ads token.
Have admin access to your Apple Ads account.
Enable Apple Ads
1. Configure token
You have to choose one of the following options for retrieving the Apple Ads Token to get started with enabling Apple Ads with Branch:
via SDK or
via Server-to-Server (S2S)
Note
For either methods, be sure to import the
AdServicesFramework to leverage the Apple Ads Attribution API.
Configure token via SDK
Implement the latest version of the Branch iOS SDK.
The Branch SDK will automatically retrieve a token on your behalf. Branch servers will use that token to call the Apple Ads Attribution API.
Configure token via server-to-server
For S2S integrations, you will need to retrieve the new token and send it to Branch on the install as apple_attribution_token. This is necessary only if you are integrating Branch through an S2S connection.
Import
AdServices.frameworkRequest attribution token. This should be available from Apple within 50ms.
func appleAttributionToken() -> String? {
if #available(iOS 14.3, *) {
return try? AAAttribution.attributionToken()
}
return nil
}+ (NSString *)appleAttributionToken {
#if !TARGET_OS_TV
if (@available(iOS 14.3, *)) {
NSError *error;
NSString *appleAttributionToken = [AAAttribution attributionTokenWithError:&error];
if (!error) {
return appleAttributionToken;
}
}
#endif
return nil;
}The token has a 24-hour time-to-live, so send it to Branch within that time to use it for attribution.
2. Connect Apple Ads in Branch
In the Branch Dashboard under Ads > Partner Management, find/search for Apple Ads or click here to go there directly.
Click the Sign in With Apple button to complete authentication. You'll also be able to select your organization here.
Click the Save & Enable button after authentication.
Afterward, you should see a successful integration status:
3. Configure attribution windows
After authenticating your Apple Ads account with Branch, navigate to the Attribution Windows tab to set windows by attribution type.
You have full freedom to choose your attribution windows; however, it may cause discrepancies between Branch and Apple Ads when comparing data if you don’t use the recommended windows.
Attribution type | Apple’s recommended attribution window |
|---|---|
click to session start | 1 day |
click to install | 7 days |
click to conversion event | 30 days |
4. Launch Apple Ads campaigns
You've now completed the setup steps! Now you can start running campaigns to see data flowing into Branch.
Note
If an Agency manages your Apple Ads campaigns, please see Agency-managed SAN Campaigns.
5. Verify data in Branch
You can go to the Ads Analytics page to view your Apple Ads performance in the Branch Dashboard.
All performance registered from Apple Ads will automatically be tagged with the Channel: Apple App Store and the Ad Partner: Apple Ads. The campaign will be set to the Campaign Name you've configured in the Apple Ads dashboard.
Info
For more details on Apple Ads reporting and analytics, view our guide here.
Apple Ads and SKAdNetwork
Apple Ads supports SKAdNetwork (SKAN) attribution tracking for SKAN versions 1.0, 2.0, and 3.0 only.
Using Apple Ads with SKAN helps you better understand how users discover and download your iOS app through Apple's advertising platform.
If you enable SKAN attribution tracking with Apple Ads, you'll get better insights into how users find your app through:
App Store search results
App Store Today tab
App Store Search tab
App Store product pages
If you want to access this new attribution data, you first need to:
Enable SKAN direct postbacks.
Have your technical team implement a simple app update.
Technical data mappings
The table in this section details how Branch maps Apple Ads fields to Branch fields.
Additional notes about the columns:
body_campaign_id: Apple will only send Branch 4 possible values for this field.last_attributed_touch_data_tilde_campaign: Branch takesbody_campaign_idand maps it to this field.Touch type: The value for this field will alway be “Taps” (clicks).
body_fidelity_type: Branch reflects the touch type in this field, using the value 1 to indicate clicks.
|
| Touch type |
|
|---|---|---|---|
10 | APPSTORE_SEARCH_RESULTS | Taps | 1 |
20 | APPSTORE_TODAY_TAB | Taps | 1 |
30 | APPSTORE_SEARCH_TAB | Taps | 1 |
40 | APPSTORE_PRODUCT_PAGES_BROWSE | Taps | 1 |
Advanced steps and troubleshooting
Install discrepancies when compared with Apple Ads dashboard
There are a few possible causes of discrepancies with Apple Ads. Due to the low customizability of Apple Ads' attribution settings, discrepancies are often higher on Apple Ads than other platforms, even though performance may be solid and reporting may be working as expected. The best way to attempt reconciliation with Apple Ads 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 Ads time zone (in Settings > Overview > Account Information ) matches your Branch Dashboard time zone (visible under Account Settings).
Limit Ad Tracking (LAT) On - Apple Ads doesn't report installs to third parties if the user has Limit Ad Tracking. However, the Apple 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 Ads attributes all installs within 30 days of an Apple 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 Ads attribution windows in Branch.
Last-click attribution - Apple Ads attributes all installs within 30 days of an Apple Ads click to itself. Branch will attribute to the last click within its attribution windows, which can often be a different source than Apple Ads.
Reinstalls - Apple 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 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 Ads responds after this timeout, Branch will not attribute the install to Apple Ads.
Opens vs. installs - Branch considers the first open to be the install. Apple 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 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 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.
You can retrieve this parameter in the app to be used for deep linking.
Installs or conversion events appearing without keywords in Branch Dashboard
There are Keyword and Search Match match sources for Apple 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 Ads dashboard.
Using TestFlight app or Developer App
If you are using the new Apple Ads framework and are debugging or testing your app using the TestFlight app or developer app, Apple 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 Apple Ads attributed campaign data in the Dashboard.
Re-Authentication
If you ever need to restart your integration with Apple Ads, you must do so by clicking the Reset Settings cog button in the Apple Ads settings in the Branch Dashboard. Clicking the Disable button at the bottom will not reset your integration. 