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

# Ad Partner Integration Guide (New)

> Connect your ad networks to Branch for seamless tracking, cost data import, and deep linking across campaigns. Optimize performance from one workspace.

## Overview

Use ad partner integrations to connect your ad networks to Branch, enabling attribution, cost data, Postbacks, and deep linking across your campaigns. Once connected, you can track performance, map events, and tune attribution windows from a single workspace.

> **Note: this guide is for new Branch**
>
> This guide covers the [new Branch experience](https://help.branch.io/marketer-hub/new-branch-overview.md). For legacy Branch, see the [legacy guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

## Before you begin

To set up an ad partner integration, you first need to have the following:

- A Branch account with access to the **Ad Partners** page under **Configuration > Ad Partners**.
- An active account with the ad partner you want to connect.
- Admin or appropriate role permissions in Branch to enable and configure integrations.

## Browse your integrations

The **Ad Partners** page is your central hub for managing all ad partner connections, SDKs, exports, webhooks, and data integrations.

At the top of the page, three health metric cards summarize your integration status:

- **Cost data coverage**: The percentage of your ad spend that Branch is capturing. A value below 100% means some partners still need cost data configured.
- **Feature utilization**: The percentage of available platform tools you're currently using.
- **SDK integration**: The status of your Branch SDK setup across platforms.

Below the metrics, a searchable card grid displays all available integrations. Each card shows the partner name, a short description, and a status badge:

- **Enabled** (green): The integration is active and configured.
- **Needs setup** (gray): The integration requires additional configuration.
- No badge: The integration hasn't been enabled yet.

Use the **Search integrations** field to find a specific partner, or select **Filters** to narrow by status or category. Select **My partners** to show only the partners you've configured.

## Enable an ad partner

Select a partner card on the **Ad Partners** page to begin setup. The experience varies depending on the partner type.

### Connect with OAuth

For partners that support OAuth authentication:

1. Select the partner card from the **Ad Partners** page.
2. On the partner's landing page, select **Sign in with [Partner]**.
3. Complete the sign-in process in the partner's authentication window.
4. If prompted, select the ad accounts you want to connect to Branch from the account checklist.
5. Select **Save**.

After authentication, Branch unlocks additional features for that partner, such as click and impression data, cost data, and engagement builder. A preview dialog may appear before authentication listing exactly which features are enabled.

### Provide account credentials

For partners that use credential-based setup:

1. Select the partner card from the **Ad Partners** page.
2. In the **Account information** dialog, enter the required identifier for that partner.
3. Select **Save**.

Refer to the individual partner guide for the specific fields required.

### Configure a self-attributing network (SAN) without OAuth

For SAN partners without an OAuth flow:

1. Select the partner card from the **Ad Partners** page.
2. Select **Enable account**.
3. In the **Account information** dialog, enter the required fields. Depending on the partner, these may include a partner identifier, attribution mode, and matching criteria.
4. Select **Save**.

Refer to the individual partner guide for the specific fields and options available.

### Enable a standard partner

For partners that don't require OAuth or credentials:

1. Select the partner card from the **Ad Partners** page.
2. On the partner's landing page, select **Enable**.

## Accept terms and conditions

Some partners require you to accept terms before completing setup. When prompted, a dialog appears with one of the following:

- **Third party integration notice**: A general data-sharing acknowledgment. Check the **I acknowledge this notice** checkbox, then select **Continue**.
- **Partner-specific terms**: Terms specific to the ad partner. Check the agreement checkbox, then select **Save** or **Continue** (the exact wording and button label vary by partner).

Review the terms carefully before accepting. You can't proceed with the integration until you acknowledge or agree.

## View integration status

After setup, the first tab on the partner page is the default view. Depending on the partner, this tab may be labeled **Status** or **Overview**. It provides a real-time overview of your integration health.

### Feature status cards

After you enable a partner, the Status tab shows a row of feature cards, one per supported capability. The cards vary by partner, so you might see a subset of the following:

- **Ad linking**: Branch Link wrapping for ads.
- **Attribution**: Install and event attribution.
- **Postbacks**: Server-to-server postbacks sent to the partner.
- **SAN API DDL**: Deferred deep linking via the SAN API.
- **Clicks & Impressions**: Click and impression data ingestion.
- **Cost data**: Ad spend data for ROI reporting.
- **Engagement builder**: Engagement-based audience tools.

Each card displays a status badge: **Enabled** (green), **Needs setup** (gray), or **Disabled** (gray). Cards that need setup display an **Enable** button to begin configuration.

![Reddit ad partner settings in Branch showing enabled and needs setup statuses for various options.](https://help.branch.io/img/Screenshot-2026-05-20-at-5.09.29-PM.png)

### Health banners

Banners at the top of the status page communicate the overall integration state:

- **Green**: All healthy. Your data streams are syncing successfully. Full performance and ROI insights are available.
- **Blue (informational)**: Action prompts, such as entering a decryption key or connecting an account. These include an action button and can be dismissed.
- **Red (error)**: Authentication errors requiring re-authentication. Select **Manage account** to resolve.

### Ad account data

Below the banners, each connected ad account displays a table with three data types:

| Data type | Details | Status |
| --- | --- | --- |
| Attribution | Sync status and data availability | Success or Needs setup |
| Click & Impression | Sync status and data availability | Success or Needs setup |
| Cost data | Import method or plan availability | Success or Needs setup |

Select **Details** on Attribution or Click & Impression rows to view expanded information. On the Cost data row, select **Learn more** to see plan availability, or **Configure** to set up cost data imports.

Alongside the data-type statuses, each connected account shows two pull timestamps:

- **Last pull**: When Branch last attempted to pull data from the account. Shows a dash (-) if no pull has run yet.
- **Last successful pull**: When Branch last completed a successful pull. Stays a dash (-) until a pull succeeds, such as while the account needs re-authentication.

## Configure events

The **Events** tab maps your Branch events to the ad partner's event names, controlling which data is shared. Not all partners display this tab. For some partners, event configuration is handled through the **Postback config** tab instead.

![Event mapping interface displaying various mobile app event statuses and corresponding names in Branch.](https://help.branch.io/img/Screenshot-2026-05-20-at-5.11.03-PM.png)

### Restrict data sharing

1. Navigate to the partner's **Events** tab.
2. Toggle **Restrict ad network data sharing** to on.
3. When enabled, this restricts which events are shared with the partner. Flag events in your SDK metadata to opt them out of sharing. Refer to the SDK documentation for details.

### Map events

1. Select **Add event** on the **Events** tab.
2. In the **Add event mapping** dialog, select your event name from the **Your event name** dropdown (for example, INSTALL).
3. Select the corresponding ad partner event name from the second dropdown (for example, first_open).
4. Select **Save**.

![Event mapping interface showing Branch and ad partner event names for mobile app installation.](https://help.branch.io/img/Screenshot-2026-05-20-at-5.12.10-PM.png)

Each event mapping appears as a row in the table. Use the toggle to enable or disable individual mappings without deleting them.

### Add conditional filters

You can add filters to control when a specific event is sent to the partner:

1. Select the pencil icon or **Add condition** link on an event row.
2. In the **Add conditional filters** dialog, configure your filter:

   - Select a **Field name** (for example, Operating system).
   - Select a **Comparator** (for example, does not equal).
   - Enter or select a **Value** (for example, robots).
3. Select **Add filter** to add more conditions.
4. Select **Save**.

> **Caution: duplicate event mappings**
>
> Duplicate event mappings (same event name and alias) trigger a validation error. Remove the duplicate to save your changes.

## Configure attribution

The **Attribution windows** tab lets you override your global attribution settings for a specific partner.

### Override global settings

1. Navigate to the partner's **Attribution windows** tab.
2. Toggle **Override global app settings** to on.
3. Edit the attribution windows as needed. The following table shows the default values:

   | Attribution type | Default | Unit |
   | --- | --- | --- |
   | Click to start session | 1 | Days |
   | Click to install | 7 | Days |
   | Click to conversion event | 30 | Days |
   | Impression to start session | 1 | Days |
   | Impression to install | 1 | Days |
   | Impression to conversion event | 7 | Days |
   | Deep linking duration | 120 | Minutes |
   | Re-engagement inactivity | 7 | Days |
   | Household measurement window | 2 | Days |
4. To limit attribution to install touches only, check **Only attribute based on install touch**. This disables re-engagement attribution and is useful for partners used exclusively for acquisition campaigns.

   1. This option is only visible for partners where it has been enabled.
5. Select **Save changes**.

A confirmation toast ("Attribution settings updated") appears when your changes are saved.

## Configure postbacks

The **Postback config** tab manages server-to-server postback URLs that notify the ad partner when events occur. Some partners display this tab in place of the **Events** tab, while others may show both.

### View postbacks

The postbacks table lists each configured event with its status and, for some partners, the full postback URL template with macro placeholders.

The **Send all events** toggle at the top of the page controls postback behavior:

- **On**: Sends active postbacks whether the event is attributed or not.
- **Off**: Sends active postbacks only for attributed events.

### Add a postback

1. Select **Add new postback** on the **Postback config** tab.
2. In the dialog, select an event from the **Event** dropdown.
3. Select **Create**.

The new postback appears in the table.

### Edit a postback

1. Select the pencil icon on the postback's row.
2. Make your changes:

   - **Status** turns the postback on or off.
   - **Send all events** sends this postback for every event, attributed or not.
   - On the **Postback URL** tab, edit the URL with **Macros**, or write it directly in **Free form code**.
3. Select **Save**.

Use the **Postback URL preview** to see the full URL and every value sent to the partner.

Changes apply only to this app, not to the partner's default template.

To remove a postback, open it and select **Delete postback**.

## Import cost data

The **Cost Import** tab lets you upload ad spend data so Branch can calculate ROI metrics. You can import data by uploading a CSV file or by configuring an email ingestor.

### Upload a CSV file

1. Navigate to the partner's **Cost Import** tab.
2. If no imports exist yet, select **Upload file** from the empty state. If imports already exist, select **New import > Upload file**.
3. In the upload dialog, select **Upload a file** and choose your CSV.
4. Select your **Ad partner account ID** and **Currency** from the dropdowns.
5. In the "Verify column headers" section, select **Auto map fields** to automatically match your CSV columns to Branch fields. A green "Synced" indicator confirms a successful mapping. You can also map columns manually using the dropdowns.
6. Review the validation status at the bottom of the dialog:

   - **"Data validated and ready for upload"** (green): Your file is ready.
   - **"X rows have errors"** (red): Review and fix the flagged rows in your CSV.
7. Select **Upload**.

An "Upload complete" toast confirms a successful import. The file appears in your "Import history" table.

### Set up an email ingestor

1. Navigate to the partner's **Cost Import** tab.
2. If no imports exist yet, select **Email ingestor** from the empty state. If imports already exist, select **New import > Setup email ingestor**.
3. In the **Email importer** dialog, configure the following:

   - **Name**: A label for this ingestor.
   - **Ad partner account ID**: The account to associate imported data with.
   - **Currency**: The currency of your cost data.
   - **Permitted domains**: The email domains allowed to send data to this ingestor.
   - **Optional test file**: Upload a sample CSV to validate the configuration.
4. Select **Run quick validation** to check your test file for errors.
5. Select **Generate**.

### View import history

The "Import history" table on the **Cost Import** tab lists all past imports with the following columns:

| Column | Description |
| --- | --- |
| File name/Importer | The source file or ingestor name |
| Import type | File upload or Email importer |
| Date & time processed/created | When the import was processed |
| Status | Pending, Active, Success, or Failed |

Select **Details** on any row to view the full import metadata, including the ad partner, account ID, currency, uploader, and timestamp.

## Manage partner settings

### View account settings

1. Select **Partner settings** on the partner's page to open the dropdown menu.
2. Select **Manage account**.
3. In the dialog, view or edit:

   - Authenticated user name and ID (read-only for OAuth partners).
   - Connected ad accounts (check or uncheck accounts to add or remove them).
   - Partner-specific fields, such as decryption keys, app IDs, or API endpoints.
4. Select **Save**.

To refresh your OAuth credentials, select **Reauthenticate** in the settings dialog. A green "Connected" badge confirms an active connection.

### Disable an integration

1. Select **Partner settings** on the partner's page to open the dropdown menu.
2. Select **Disable integration**.
3. Confirm the action in the dialog that appears.

Disabling an integration is reversible. You can re-enable the partner and its existing configuration at any time.

### Delete an integration

1. Select **Partner settings** on the partner's page to open the dropdown menu.
2. Select **Delete integration**.
3. Review the confirmation dialog. The warning message depends on the partner type:

   - **Custom partners**: "This action is permanent and cannot be undone. Deleting a partner with active links will immediately break analytics tracking."
   - **Standard partners**: "All current credentials, post backs, event mappings and attribution windows will be deleted. This partner will be disabled and must be fully re-configured to be used again."
   - **Deprecated partners**: "This ad partner is no longer supported and cannot be re-enabled. To maintain accurate tracking, please migrate your links to a supported partner."
4. Select **Delete ad partner**.

> **Warning**
>
> Deleting a partner is permanent. For custom and deprecated partners, the action can't be undone. Make sure you've migrated any active links before proceeding.

## Add a custom ad partner

A custom partner is a partner you add yourself because Branch does not have an integration with them. This is different from a partner with a dedicated integration guide.

If your ad partner isn't available in the default integration catalog, you can create a custom partner:

1. On the **Ad Partners** page, select **Create new**.
2. Select **Custom partner (X/25)** from the dropdown, where X is the number of custom partners you've already created.
3. In the **Add custom partner** dialog, enter a name for the partner.
4. Select **Save**.

The new partner appears in your integration grid with an **Enabled** badge. You can then configure postbacks, attribution, and events like any other partner.

> **Note**
>
> You can create up to 25 custom partners per account. The dropdown shows your current usage (for example, "Custom partner (1/25)").