Overview
Apple Ads is a self-attributing network (SAN) that drives iOS app discovery and downloads through the App Store. Connect Apple Ads to Branch to attribute installs and conversions, configure attribution windows, and pull cost data into a single workspace.
For more information about integrating ad partners in general, visit our Ad Partner Integration Guide.
Note: this guide is for new Branch
This guide covers integrating Apple Ads in the new Branch experience. For information on Apple Ads in legacy Branch, visit our legacy guide.
Partner capabilities
Capability | Details |
|---|---|
Company type | Self-Attributing Network |
Deep linking | Limited (campaign value pass-back only) |
Attribution | Click-through attribution, View-through attribution |
Ad campaign types | Acquisition campaigns |
Supported platforms | iOS |
Cost ingestion support | Supported (via API) |
Pricing models | CPT (cost per tap), CPI |
Engagement Builder Ad Partner Integration | Not available |
Before you begin
To set up the Apple Ads integration, you need:
Branch's Performance product enabled for your Branch account. Contact your Branch account manager or visit https://branch.io/pricing.
A Branch account with access to Configuration > Ad Partners and admin permissions to enable and configure integrations.
An Apple Ads account with admin access.
A mobile developer to implement the Apple Ads token in your app.
Configure the Apple Ads token
Before enabling Apple Ads in Branch, your developer must retrieve the Apple Ads token using one of the following methods:
via SDK, or
via Server-to-Server (S2S)
For implementation details, see the Configure Apple Ads Token guide in Developer Hub.
Enable Apple Ads
To begin, navigate to Configuration > Ad Partners > Apple Ads.
Apple Ads is an OAuth partner. Follow Connect with OAuth in the general Ad Partner Integration Guide. When prompted, select Sign in with Apple Ads and authenticate with your Apple Account.
A single sign-in covers all Apple Ads features in Branch: ad linking, attribution, clicks and impressions, and cost data.
To manage the connected user later, see Manage partner settings
Configure attribution
Apple Ads supports seven attribution windows. The defaults for the three click-based windows match Apple's recommended values.
To configure attribution windows, select the Attribution windows tab on the Apple Ads page.
Attribution type | Default | Apple's recommendation |
|---|---|---|
Click to start session | 1 day | 1 day |
Click to install | 7 days | 7 days |
Click to conversion event | 30 days | 30 days |
Impression to start session | 1 day | — |
Impression to install | 1 day | — |
Impression to conversion event | 6 days | — |
Household measurement window | 1 day | — |
Using non-recommended values for the three click-based windows may cause discrepancies between Branch and Apple Ads when comparing data.
Note: tap vs. impression
Apple Ads always reports the attributed touch type as a tap, even when the conversion is attributed to an impression. Branch supports view-through conversions for Apple Ads, so the impression windows above control how Branch attributes those conversions, even though the touch itself is recorded as a tap (see ).
For more information, follow Configure attribution in the general ad partner integration guide.
Verify your data
In Branch Liveview: confirm that events from your app appear in real time. This is the fastest way to confirm SDK events are firing.
In Branch Analysis dashboards: review attributed installs, events, and cost data tagged with
Ad Partner Name = Apple Search Ads. The campaign field is set to theCampaign Nameconfigured in your Apple Ads account.
Note: Agency management
If an Agency manages your Apple Ads campaigns, see Agency-managed SAN Campaigns.
Apple privacy frameworks
SKAdNetwork
Apple Ads supports SKAdNetwork (SKAN) attribution tracking for SKAN versions 1.0, 2.0, and 3.0 only.
Using Apple Ads with SKAN provides insight into how users discover and download your iOS app through:
App Store search results
App Store Today tab
App Store Search tab
App Store product pages
To access this attribution data:
Enable SKAN direct postbacks.
Have your technical team implement a simple app update.
Ad Attribution Kit
Ad Attribution Kit (AAK) is Apple's attribution framework that succeeds SKAN. Branch supports AAK for Apple Ads campaigns.
To use AAK with Branch for Apple Ads attribution, add AAK configuration to your app's Info.plist file in addition to your existing SKAdNetwork entries. Follow Apple's AAK configuration guide for details.
Caution: iOS 26.2+
Apps without AAK configuration will experience attribution interruption for Apple Ads as users upgrade to iOS versions 26.2+.
Data mappings
Branch receives Apple Ads data from two sources: SKAdNetwork (SKAN) postbacks and reports from the Apple Ads API. The mappings for each source are listed below.
SKAN postback mappings
The following mappings apply to SKAN postback data only. Branch maps Apple Ads body_campaign_id values to channel names. Apple sends only the four values listed below.
|
| 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 |
Notes:
last_attributed_touch_data_tilde_campaign: Branch mapsbody_campaign_idto this field.Touch type is always "Taps" (clicks).
body_fidelity_typeis always1, indicating clicks.
Apple Ads API report mappings
Branch fetches two types of reports from the Apple Ads API: keyword-level and ad-level.
These reports are different, but they share some fields in common. The tables below outline which fields are exclusively in keyword-level reports, which fields are exclusively in ad-level reports, and which fields are in both (universal). The fields Branch receives from the Apple API are mapped to the Branch fields listed in each table.
You can use the mapped Branch fields in your Analysis dashboards to measure your campaign performance. These fields are also available in Branch's Query API in all EO topics.
Keyword-level fields
The following fields are included only in keyword-level reports:
Apple Ads Parameter | Branch Mapped Field |
|---|---|
|
|
|
|
Ad-level fields
The following fields are included only in ad-level reports:
Apple Ads Parameter | Branch Mapped Field |
|---|---|
|
|
|
|
|
|
|
|
Universal fields
The following fields are included in both keyword-level and ad-level reports:
Apple Ads Parameter | Branch Mapped Field |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note: placement values
The
supplyPlacementvalue indicates the App Store placement where the ad ran:APPSTORE_SEARCH_RESULTS,APPSTORE_SEARCH_TAB,APPSTORE_TODAY_TAB, orAPPSTORE_PRODUCT_PAGES_BROWSE. Use this field to break out Apple Ads performance by placement.
Default behavior
Since some fields are included in both keyword-level and ad-level reports, Branch prevents duplication by setting a default data source to pull from when dimensions from both types of reports are requested.
The default data source is keyword-level reports.
This means:
If only keyword-level (or keyword-level and universal) dimensions are pulled, then the keyword-level report is the data source.
If only ad-level (or ad-level and universal) dimensions are pulled, then the ad-level report is the data source.
If both keyword-level and ad-level (or keyword-level, ad-level, and universal) dimensions are pulled, then the keyword-level report is the data source.
Recommendations
Branch recommends that you set up two reports: a keyword-level report and an ad-level report, to mirror the setup of the Apple API reporting structure.
For the keyword-level report, include as many keyword-level and universal dimensions as you are interested in.
For the ad-level report, include as many ad-level and universal dimensions as you are interested in.
For simplicity, avoid including exclusively keyword-level and exclusively ad-level fields in the same report.
Troubleshooting
Install discrepancies compared with the Apple Ads dashboard
Discrepancies between Branch and Apple Ads are often higher than with other partners due to Apple Ads' attribution model. To attempt reconciliation, compare Apple Ads' 'New Download' counts (minus the LAT-on percentage) against Branch's first-open counts for Apple Ads.
Time zones — Ensure your Apple Ads time zone (Settings > Overview > Account Information) matches your Branch time zone (Configuration > App Settings > General).
Limit Ad Tracking (LAT) On — Apple Ads doesn't report installs to third parties when LAT is on, but the Apple Ads dashboard shows all installs regardless. With AAK properly configured, attribution is still provided for LAT-on or ATT opted-out users.
Attribution windows — Apple Ads attributes all installs within 30 days of a click; Branch's default click-to-install window is 7 days. Adjust in the Attribution tab on the Apple Ads page.
Last-click attribution — Branch attributes to the last click within its windows; Apple Ads always attributes to itself within 30 days. Source mismatches are expected.
Reinstalls — Apple Ads counts reinstalls as conversions by default; Branch labels these "REINSTALLS." In the Apple Ads dashboard, switch the column selector to New Downloads or Redownloads to align.
Attribution API timeouts — If the Apple Ads Attribution API doesn't respond within ~1 second, Branch won't attribute the install to Apple Ads.
Opens vs. installs — Branch counts the first app open as the install; Apple Ads counts the download. Counts and dates may differ.
Deep linking with Apple Ads
Apple Ads doesn't use Branch Links, so deep linking is limited. Branch passes back the campaign value you configure in the Apple Ads dashboard. You can read this parameter in-app to drive deep linking.
Installs or conversion events appearing without keywords
Apple Ads offers Keyword and Search Match match sources. Search Match automatically matches your ad to relevant App Store searches rather than preassigned keywords, so its attributed installs have no associated keywords. Toggle Search Match at the Ad Group level in the Apple Ads dashboard.
Using TestFlight or a developer app
When debugging via TestFlight or a developer app, Apple Ads returns dummy values with Campaign ID 1234567890. Filter this out when reviewing Apple Ads-attributed data in Branch.