> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Enable Apple Ads (New)

> Integrate Apple Ads with Branch for effective iOS app discovery, attribution, and cost data management to boost your app's performance.

## 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](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

> **Note: this guide is for new Branch**
>
> This guide covers integrating Apple Ads in the [new Branch experience](https://help.branch.io/marketer-hub/new-branch-overview.md). For information on Apple Ads in legacy Branch, visit our [legacy guide](https://help.branch.io/marketer-hub/enable-apple-ads-new.md).

### 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:

- Ad partner integrations enabled for your Branch account. Availability varies by Branch plan. See [Branch pricing](https://www.branch.io/pricing/) or contact your Branch representative.
- 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](https://help.branch.io/developer-hub/configure-apple-ads-token.md) 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](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md) in the general [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md). 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](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md#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.

For more information, follow [Configure attribution](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md) in the general ad partner integration guide.

## Verify your data

- **In Branch** [**Liveview**](https://app.branch.io/testing-and-monitoring/events): 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**](https://help.branch.io/marketer-hub/analysis-data-sources-new.md#skadnetwork): review attributed installs, events, and cost data tagged with `Ad Partner Name = Apple Search Ads`. The campaign field is set to the `Campaign Name` configured in your Apple Ads account.

> **Note: Agency management**
>
> If an Agency manages your Apple Ads campaigns, see [Agency-managed SAN Campaigns](https://help.branch.io/marketer-hub/what-is-a-self-attributing-network.md#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:

1. Enable SKAN direct Postbacks.
2. 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](https://developer.apple.com/documentation/adattributionkit/configuring-an-advertised-app) 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.

| `body_campaign_id` | `last_attributed_touch_data_tilde_campaign` | Touch type | `body_fidelity_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 maps `body_campaign_id` to this field.
- **Touch type** is always "Taps" (clicks).
- `body_fidelity_type` is always `1`, indicating clicks.

### Apple Ads API report mappings

Branch fetches two [types of reports](https://developer.apple.com/documentation/apple_ads) 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](https://help.branch.io/marketer-hub/analysis-dashboards-overview-new.md) to measure your campaign performance. These fields are also available in Branch's [Query API](https://help.branch.io/apidocs/query/overview.md) in all EO topics.

#### Keyword-level fields

The following fields are included **only** in keyword-level reports:

| Apple Ads Parameter | Branch Mapped Field |
| --- | --- |
| `keyword` | `last_attributed_touch_data_tilde_keyword` |
| `keywordId` | `last_attributed_touch_data_tilde_keyword_id` |

#### Ad-level fields

The following fields are included **only** in ad-level reports:

| Apple Ads Parameter | Branch Mapped Field |
| --- | --- |
| `adName` | `last_attributed_touch_data_tilde_ad_name` |
| `adId` | `last_attributed_touch_data_tilde_ad_id` |
| `creativeName` | `last_attributed_touch_data_tilde_creative_name` |
| `creativeId` | `last_attributed_touch_data_tilde_creative_id` |

#### Universal fields

The following fields are included in **both** keyword-level and ad-level reports:

| Apple Ads Parameter | Branch Mapped Field |
| --- | --- |
| `campaignName` | `last_attributed_touch_data_tilde_campaign` |
| `campaignId` | `last_attributed_touch_data_tilde_campaign_id` |
| `adGroupName` | `last_attributed_touch_data_tilde_ad_set_name` |
| `adGroupId` | `last_attributed_touch_data_tilde_ad_set_id` |
| `orgId` | `last_attributed_touch_data_tilde_advertising_account_name` |
| `countryOrRegion` | `last_attributed_touch_data_tilde_country_or_region` |
| `supplyPlacement` | `last_attributed_touch_data_tilde_placement` |

> **Note: placement values**
>
> The `supplyPlacement` value indicates the App Store placement where the ad ran: `APPSTORE_SEARCH_RESULTS`, `APPSTORE_SEARCH_TAB`, `APPSTORE_TODAY_TAB`, or `APPSTORE_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**](https://help.branch.io/account-hub/general-new.md#timezone)).
> - **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](https://help.branch.io/developer-hub/ios-advanced-features.md#general-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.