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

# Enable Meta Ads (New)

> Run effective Meta Ads campaigns across Facebook, Instagram, and Messenger with Branch's integration for accurate attribution and cost tracking.

## Overview

Meta Ads (formerly Facebook Ads) lets you run advertising campaigns across Facebook, Instagram, Audience Network, and Messenger from a single platform. Branch's Meta Ads integration tracks attribution for installs and post-install events, imports cost data, and supports the iOS privacy frameworks used in Meta campaigns: Apple's SKAdNetwork (SKAN) and Meta's Aggregated Event Measurement (AEM).

Meta is a self-attributing network (SAN), which means Meta runs its own attribution and reports results back to Branch via API rather than receiving traditional Postbacks from Branch.

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**
>
> Please note that this guide is about integrating Meta Ads in the [new Branch experience](https://help.branch.io/marketer-hub/new-branch-overview.md). For information on Meta Ads in legacy Branch, visit our [legacy guide](https://help.branch.io/marketer-hub/meta-ads-overview.md).

### Partner capabilities

| Capability | Details |
| --- | --- |
| Company type | Self-attributing network (SAN) |
| Deep linking | Supported ([SAN API-Driven Deferred Deep Linking](https://help.branch.io/developer-hub/san-deferred-deep-linking.md)) |
| Attribution | Click-through attribution, View-through attribution (with SKAN and AEM on iOS) |
| Ad campaign types | Awareness, Consideration, Conversion (web and app) |
| Supported platforms | iOS, Android, Web |
| Cost ingestion support | Supported (via API) |
| Pricing models | CPC, CPM, CPA |
| Engagement Builder Ad Partner Integration | [Available](https://help.branch.io/marketer-hub/enable-engagement-builder.md) |

Branch also supports engaged attribution for Meta: [Engaged View-through attribution](https://help.branch.io/marketer-hub/engagement-attribution-for-sans.md) and [Engaged Click-through attribution](https://help.branch.io/marketer-hub/engagement-attribution-for-sans.md).

> **Note: limited tracking link support**
>
> Meta has confirmed that impression tracking links are not supported in any ad placement, and click tracking links are only supported in a subset of placements. For most campaigns, attribution flows through Meta's APIs (SAN, SKAN, AEM) rather than tracking link redirects.

## Before you begin

To set up the Meta Ads integration, you need:

- A Branch account with access to **Configuration > Ad Partners** and admin permissions to enable and configure integrations.
- A Meta Ads account with admin access through Meta Business Manager.
- 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.

## Enable Meta Ads

To begin, navigate to **Configuration > Ad Partners > Meta**.

Meta is an OAuth partner. Follow [Connect with OAuth](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md#connect-with-oauth) in the general [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md) to sign in and connect your Meta Ads accounts.

> **Warning: Meta Account ID**
>
> Do not reuse a Meta Account ID across multiple apps. If you have more than one app using the same Meta Account ID, SKAN data may appear in only one of those apps. Use a distinct Meta Account ID per app to avoid visualization issues.

## Configure attribution

To configure attribution windows, select the **Attribution windows** tab on the Meta page.

| Attribution type | Default | Meta's recommendation |
| --- | --- | --- |
| Click to conversion event | 28 days | — |
| Click to install | 7 days | 7 days |
| Click to start session | 1 day | — |
| Household measurement window | 2 days | — |
| Impression to conversion event | 7 days | — |
| Impression to install | 1 day | 1 day |
| Impression to start session | 1 day | — |

> **Tip: attribution window alignment**
>
> Meta's iOS attribution defaults to a 7-day click and 1-day view window. If you want Branch's Meta attribution to match Meta's own reporting as closely as possible, use those values for Click to install and Impression to install.

## Configure events

To configure event mappings, select the **Event config** tab on the Meta page.

Meta uses event mappings to optimize campaigns and to feed the AEM and SKAN frameworks. Follow [Configure events](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md#configure-events) in the general [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md) for the event mapping flow. The full Branch-to-Meta event name reference is in [Data mappings](#data-mappings) below.

## Verify your data

After your integration is connected and events are flowing, you can verify data is reaching Meta and Branch:

- **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 where `Ad Partner Name = Facebook`.
- **In Meta Events Manager**: check the Activity tab to confirm mapped events are being received. Look for any errors or warnings about event eligibility.
- **In Meta Ads Manager**: when creating a campaign, your mapped events should appear as available optimization events. If an event doesn't appear, it may not be eligible for AEM or SKAN.

## Meta privacy frameworks

Meta supports two privacy-preserving measurement frameworks for iOS 14.5+: SKAN (Apple's framework) and AEM (Meta's framework). The two work in parallel and can run on the same campaign.

### SKAdNetwork

Meta handles SKAN differently from most ad partners. Meta does not forward individual SKAN postbacks to Branch. Instead, Meta collects and validates postbacks internally and shares aggregate data with Branch through Meta's Ads Insights API.

**Supported campaign types for SKAN data:**

| Meta campaign type | SKAN data shared with Branch |
| --- | --- |
| Mobile App Install (MAI) | ✅ |
| App Event Optimization (AEO) | ✅ |
| Value Optimization (VO) | ✅ |
| All other campaign types | ❌ |

**Data dimensions available via the Ads Insights API:**

| Parameter | Shared by Meta |
| --- | --- |
| Download/Install | ✅ |
| Reinstall | ❌ (counted as Install) |
| Conversion Value | ✅ |
| Campaign Name | ✅ |
| Campaign ID | ✅ |

#### Sync Branch's conversion value schema with Meta

If you use a Branch SDK for SKAN support, paste Branch's conversion value schema URL into Meta Events Manager so Meta can optimize campaigns using your Branch conversion values.

> **Caution: skip this step if you use the Facebook SDK for SKAN**
>
> If you use the Facebook SDK for SKAN, you do not need to sync Branch’s conversion value schema with Meta. Meta pulls its own conversion value schema automatically. If you call SKAN methods natively in your app, Meta recommends configuring conversion values in Meta Events Manager directly rather than using Branch's endpoint.

1. In Branch, navigate to **Configuration > Ad Partners > Meta** and find the **Conversion value URL** field. The URL follows this format, with your app's iTunes ID auto-filled: `https://api2.branch.io/v3/partners/a_facebook/conversion-value-mappings?app_id={itunes_id}`
2. Select the **copy icon** to copy the URL with your iTunes ID populated.
3. In Meta Ads Manager, open **Events Manager** and select your app.
4. Open **Settings**, then under **Configure App Events for SKAdNetwork**, select **Set Up Events**.
5. Select **Import from Partner App**.
6. Paste the URL from step 2 and select **Connect**.

   1. Important: Meta will return a connection error if your app isn't enabled for SKAN in Branch, or if you haven't mapped at least one conversion value. Configure both before pasting the URL.

### Aggregated Event Measurement (AEM)

Meta's Aggregated Event Measurement (AEM) is a privacy-preserving protocol that measures iOS 14.5+ app installs and post-install events without relying on the IDFA. AEM runs alongside SKAN and provides faster, campaign-level attribution.

**Supported campaign types for AEM:**

| Campaign type | Description |
| --- | --- |
| Mobile App Install (MAI) | App promotion campaigns. Work automatically once AEM is enabled. |
| Mobile App Engagement (MAE) | Sales (with or without catalog), Lead, and Engagement campaigns destined to a mobile app. Requires deep linking to be configured. |

> **Caution: AEM data takes priority**
>
> When both AEM and Branch Link data appear for the same traffic, Branch defers to AEM data for last-touch attribution. This is intentional and aligns with Meta's preferred attribution method.

#### Enable AEM

> **Note: SDK version requirement**
>
> AEM requires the Branch iOS SDK version 2.1.2 or later. If your app uses an older version, work with your development team to update before enabling AEM.

1. Contact your Meta Account Manager and request that AEM be enabled for your account. Meta must enable AEM on their side before you can activate it in Branch.
2. (Optional) In Meta Events Manager, set MMP as your preferred connection method for your app. Ensure install and post-install events use the same connection method. See [Meta's documentation](https://www.facebook.com/business/help/3215014965459549) for steps.
3. In Branch, navigate to **Configuration > Ad Partners > Meta > Event config**.
4. Below your event mappings, toggle **Enable Aggregated Event Measurement (AEM)** to on.

> **Warning: re-toggle AEM after SDK updates**
>
> If your development team updates the Branch iOS SDK, re-toggle the AEM switch in Branch to make sure data continues flowing.

#### AEM data in Branch

AEM provides the following campaign-level fields:

- `campaign_id`: Meta campaign identifier
- `ad_id`: ad identifier
- `creative_id`: creative identifier
- `ad_set_id`: ad set identifier
- `secondary_publisher`: placement (Instagram, Facebook, Audience Network, etc.)

> **Note: use campaign_id instead of campaign_name**
>
> Meta doesn't provide `campaign_group_name` for AEM, so the `campaign_name` field in Branch reports and exports shows as `Unpopulated`. Use `campaign_id` to identify campaigns instead. This is a Meta limitation that affects all MMPs using AEM.

AEM-attributed events appear in Branch within minutes to hours and are included in standard last-touch attribution. Allow up to 24 hours for full propagation through Meta's systems, and 24–48 hours after launching your first AEM campaign to see meaningful data.

### Limited Data Use (LDU)

On July 1st, 2020, Facebook introduced a new [Limited Data Use (LDU)](https://www.facebook.com/business/help/1151133471911882) feature to support customer compliance with the California Consumer Privacy Act (CCPA). This feature enables you to limit how Meta uses the data of users in states where Limited Data Use is available. This data could be collected by you or by third parties on your behalf.

If the Limited Data Use feature is enabled, Meta will process data in accordance with its role as a service provider or processor with respect to flagged personal information from people in states where Limited Data Use is available. This means Meta will limit use of that data subject to their [State-Specific Terms](https://www.facebook.com/legal/terms/state-specific).

To invoke Meta Limited Data Use for your users, please use any [Consumer Protection Preference](https://help.branch.io/developer-hub/honoring-opt-out-of-processing-requests.md#configure-sdk-privacy-controls) other than [FULL](https://help.branch.io/developer-hub/honoring-opt-out-of-processing-requests.md#using-sdk-privacy-controls).

## Data mappings

### Event names

Branch maps standard Meta event names to Branch event names automatically. When tracking a Meta event that maps to the Branch `Custom` event, use the Meta event name with `branch.logevent('AdClick')` syntax. See the [Branch event tracking guide](https://help.branch.io/developer-hub/track-branch-events.md) for implementation details.

| Branch event name | Meta event name |
| --- | --- |
| `INSTALL` | `MOBILE_APP_INSTALL` |
| `OPEN` | `fb_mobile_activate_app` |
| `REINSTALL` | `fb_mobile_activate_app` |
| `ADD_TO_CART` | `fb_mobile_add_to_cart` |
| `PURCHASE` | `fb_mobile_purchase` |
| `VIEW_ITEM` | `fb_mobile_content_view` |
| `ACHIEVE_LEVEL` | `fb_mobile_level_achieved` |
| `ADD_PAYMENT_INFO` | `fb_mobile_add_payment_info` |
| `ADD_TO_WISHLIST` | `fb_mobile_add_to_wishlist` |
| `COMPLETE_TUTORIAL` | `fb_mobile_tutorial_completion` |
| `INITIATE_PURCHASE` | `fb_mobile_initiated_checkout` |
| `RATE` | `fb_mobile_rate` |
| `SEARCH` | `fb_mobile_search` |
| `SPEND_CREDITS` | `fb_mobile_spent_credits` |
| `UNLOCK_ACHIEVEMENT` | `fb_mobile_achievement_unlocked` |
| `SUBSCRIBE` | `Subscribe` |
| `START_TRIAL` | `StartTrial` |
| `VIEW_AD` | `AdImpression` |
| `CLICK_AD` | `AdClick` |

### Campaign and ad data

> **Note: advertising partner name value**
>
> The `~advertising_partner_name` field populates as **Facebook** for Meta Ads traffic, not "Meta". Use `Ad Partner Name = Facebook` when filtering in Branch dashboards or exports.

| Branch field | Meta field |
| --- | --- |
| `~advertising_partner_name` | `Facebook` (static value) |
| `~ad_set_name` | `campaign_name` |
| `~ad_set_id` | `campaign_id` |
| `~secondary_publisher` | `publisher_platform` |
| `~creative_name` | `creative_name` |
| `~creative_id` | `creative_id` |
| `~ad_name` | `adgroup_name` |
| `~ad_id` | `adgroup_id` |
| `~campaign` | `campaign_group_name` |
| `~campaign_id` | `campaign_group_id` |

> **Caution: server-side creative fields**
>
> The `creative_id` and `creative_name` fields are populated server-side by Meta on cost, clicks, and impressions sent to Branch. These are not configured in Branch.

### Metadata

The table below shows how Branch SDK fields map to Meta MMP fields, and which Meta events each mapping is supported on.

**Meta content events** in the supported events column refers to this set: `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, and `fb_mobile_search`.

| Branch SDK field | Meta MMP field | Meta event(s) supported |
| --- | --- | --- |
| `event_data.revenue` | `_valueToSum` | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_spent_credits`, `fb_mobile_content_view` |
| `event_data.currency` | `fb_currency` | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_content_view` |
| `content_items[i].$quantity` | `fb_num_items` | `fb_mobile_initiated_checkout`, `fb_mobile_purchase` |
| `content_items` (array) | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$sku` | `fb_content_id` | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$product_category` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$product_brand` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$product_name` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$price` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$og_title` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$keywords` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `content_items[i].$custom_fields` | `fb_content` (array) | `fb_mobile_add_to_cart`, `fb_mobile_add_to_wishlist`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search` |
| `event_data.search_query` | `fb_search_string` | `fb_mobile_search` |
| `custom_data.fb_payment_info_available` | `fb_payment_info_available` | `fb_mobile_initiated_checkout` |
| `custom_data.level` | `fb_level` | `fb_mobile_level_achieved` |
| `custom_data.fb_success` | `fb_success` | `fb_mobile_add_payment_info`, `fb_mobile_tutorial_completion`, `fb_mobile_search` |
| `custom_data.fb_registration_method` | `fb_registration_method` | `fb_mobile_complete_registration` |

Branch sends all content items tracked for an event when supported. If the advertiser tracks `ContentMetadata` through the Branch SDK, Branch automatically maps `"fb_content_type":"product"` for in-app events. Otherwise, `fb_content_type` is not added.

## Data limitations

Please note the following Meta-specific data behaviors in Branch:

- **Redacted data**: Meta may redact specific metrics or events when aggregation levels aren't high enough to prevent de-anonymization, or for non-aggregated view-through and click-through data. Redacted values appear as "undisclosed" in Branch and `null` in Aggregate Exports.
- **Android event detail**: For Android events specifically, you can retrieve event detail (rather than "undisclosed") by enabling [Meta Install Referrer](https://help.branch.io/developer-hub/meta-install-referrer.md).
- **Device-level data to third parties**: Branch cannot send device-level Meta attribution data to third parties unless attribution flowed through Meta Install Referrer or AEM.
- **Deep link session callback**: Meta attribution data is not returned in the deep link session initialization callback inside the app.
- **60-day purge**: Branch purges last-attributed Meta data after 60 days.

### Feature support for Meta data

| Branch feature | Meta data included |
| --- | --- |
| Dashboard visualizations | Pre-aggregated analytics |
| Query API | Pre-aggregated analytics |
| Liveview | Pre-aggregated analytics |
| CSV Exports | Pre-aggregated analytics |
| Webhooks | Pre-aggregated analytics |
| Daily Export API | Not supported |
| Data Integrations | Not supported |

## Troubleshooting

> **My AEM events show as "Ineligible"**
>
> This usually means AEM was toggled on in Branch before AEM was enabled in Meta. Set up AEM in Meta first, then enable it in Branch. If you've already hit this, toggle the AEM switch off and back on in Branch to recover.

> **I get a connection error when pasting the SKAN conversion value URL in Meta**
>
> Meta returns a connection error if Branch can't supply a conversion value response. Confirm that:
>
> - Your app is enabled for SKAN in Branch. See [Enable SKAdNetwork](https://help.branch.io/marketer-hub/enable-skadnetwork.md).
> - You've mapped at least one conversion value in the Branch dashboard. Without a mapping, Meta gets an empty response.

> **SKAN data in Branch looks delayed**
>
> Meta's SKAN dashboard data is reflected by the Meta conversion date rather than the Branch ingestion date. This produces a delay similar to cost data on traditional SAN install campaigns. Allow 24–48 hours after implementation before troubleshooting further.

> **Branch and Meta numbers don't match**
>
> Meta and Branch can show different totals for the same campaign because of attribution window differences, late conversions, redaction thresholds, and aggregation rules. See [Common Sources of SAN Reporting Discrepancies](https://help.branch.io/marketer-hub/common-sources-of-san-reporting-discrepancies.md) for the full list of expected differences.

> **Where do I see Meta SKAN data in Branch?**
>
> To see Meta SKAN data in the [new Branch experience](https://help.branch.io/marketer-hub/new-branch-overview.md), use the SKAN or Unified + SKAN data source for [Analysis dashboards](https://help.branch.io/marketer-hub/analysis-data-sources-new.md#skadnetwork) and set `Ad Partner Name = Facebook`.

## Additional resources

For additional questions, see the [Meta Ads FAQ](https://help.branch.io/marketer-hub/meta-ads-faq.md) and [Meta Advanced Mobile Measurement](https://help.branch.io/marketer-hub/meta-advanced-mobile-measurement.md) guides.