Overview
X Ads is a self-attributing network (SAN) that enables Branch to receive attribution data for installs and in-app events from X ad campaigns. This integration sends app conversion data collected by the Branch SDK to X for attribution and provides access to attribution data in Branch for analysis.
As a SAN, X reports attribution to Branch directly via its API. For more information about integrating ad partners in general, visit our Ad Partner Integration Guide.
Note: this guide is for new Branch
Please note that this guide is about integrating X Ads in the new Branch experience. For information on X Ads in legacy Branch, visit our legacy guide.
Partner capabilities
| Capability | Details |
|---|---|
| Company type | Self-attributing network (SAN) |
| Deep linking | Not supported for app campaigns. Branch Links can be used on posts and non-app campaign types but will only report in Branch. |
| Attribution | Click-through, view-through |
| Ad campaign types | App installs, app re-engagements |
| Supported platforms | iOS, Android |
| Cost ingestion support | Supported (via API) |
| Pricing models | CPC, CPM, CPI |
| Engagement Builder Ad Partner Integration | Not available |
Before you begin
To set up the X Ads integration, you need:
- Ad partner integrations enabled for your Branch account. Availability varies by Branch plan. See Branch pricing or contact your Branch representative.
- A Branch account with access to Configuration > Ad Partners and admin permissions to enable and configure integrations.
- An X Ads account with permissions to configure ad accounts.
Enable X Ads
To begin, navigate to Configuration > Ad Partners > Twitter.
Caution: Branch must be your only MMP
Ensure Branch is the only mobile measurement partner (MMP) configured in your X Ads account before enabling this integration. If another MMP is already configured, you must remove it first, otherwise the connection will fail.
- Select Enable.
- Enter your X user name and X user ID to authorize Branch.
- Review and accept the X Ads Terms & Conditions.
- Under Ad Accounts, select the X Ads accounts you want to connect to Branch.
- Select Save.
Note: connecting multiple accounts
X Ads accepts multiple ad accounts. However, only a single Branch user can authenticate the integration. That user must have access to all accounts you want to connect before signing in.
Configure attribution
To configure attribution windows, select the Attribution windows tab on the X page.
To minimize discrepancies when comparing Branch and X Ads reporting, match your Branch attribution windows to the settings in your X Ads account.
| Attribution type | Default |
|---|---|
| Click to conversion event | 30 days |
| Click to install | 30 days |
| Click to start session | 30 days |
| Household measurement window | 2 days |
| Impression to conversion event | 1 day |
| Impression to install | 1 day |
| Impression to start session | 1 day |
Configure events
To configure event mappings, select the Event config tab on the Twitter page.
Branch forwards in-app events to X Ads based on the mappings configured here. For guidance on setting up event mappings, see the general Ad Partner Integration Guide.
Verify your data
After enabling the integration and running campaigns, verify that attribution data is flowing correctly.
- 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 where
Ad Partner Name = Twitter. - In X Ads: confirm that attributed installs and events are appearing in your X Ads campaign reporting.
X Ads data sharing
X has a data-sharing agreement with Branch that restricts how attribution data is accessed and exported. Understanding these restrictions is important when setting up data feeds or working with agencies.
Data levels
Source level includes publisher name (hardcoded to "Twitter"), publisher ID, and ~advertising_partner_name (hardcoded to "Twitter").
Campaign level includes campaign name, campaign ID, channel (Twitter or Twitter Audience Platform), ad ID (Post ID), and partner ad set ID (Line Item ID).
Accessible data
By default, Branch's API and Analysis dashboards provide source and campaign level data in aggregate reports. In exports, only source level data is available by default. Campaign level data in exports requires allowlisting. To request campaign level data export access, contact your Branch representative with the subject line CAMPAIGN LEVEL DATA EXPORT ALLOWLIST.
X attribution data cannot be forwarded to Branch data integrations (such as third-party analytics providers). If Postbacks are configured to analytics providers, source and campaign level information will be scrubbed by default, only identifiers will pass through, and conversions will appear organic to the third party.
Agency access
Agencies can access X Ads attribution data in Branch if they have been granted full agency access by the client, or if they append their agency attribution code to the X Ads campaign they are running.
Data mappings
Campaign data
Branch maps the following data fields from X Ads to Branch.
Note: advertising_partner_name value
The value of ~advertising_partner_name for X Ads is "Twitter", not "X" or "X Ads". Use Ad Partner Name = Twitter when filtering in Branch analytics.
| Branch field | X Ads data | Possible values |
|---|---|---|
~advertising_partner_name | — | "Twitter" |
~channel | tpn_attribution | "Twitter" (standard) or "Twitter Audience Platform" (if TAP is last touch) |
~campaign | campaign_name | The name of your X Ads campaign |
~campaign_id | campaign_id | The ID of your X Ads campaign |
~user_data_geo_country_code | country_code | Two-letter country code (e.g., US) |
last_touch_type | engagement_type | CLICK or IMPRESSION |
last_attributed_touch_timestamp | engagement_time | Timestamp of the ad click or impression |
Event names
Branch forwards in-app events to X Ads using the following event name mappings. Configure these on the Event config tab.
| Branch event name | X Ads event name |
|---|---|
| ACHIEVE_LEVEL | LEVEL_ACHIEVED |
| ADD_PAYMENT_INFO | ADDED_PAYMENT_INFO |
| ADD_TO_CART | ADD_TO_CART |
| ADD_TO_WISHLIST | ADD_TO_WISHLIST |
| COMPLETE_REGISTRATION | SIGN_UP |
| COMPLETE_TUTORIAL | TUTORIAL_COMPLETE |
| INITIATE_PURCHASE | CHECKOUT_INITIATED |
| INSTALL | INSTALL |
| LOGIN | LOGIN |
| OPEN | RE_ENGAGE |
| PURCHASE | PURCHASE |
| RATE | RATED |
| REINSTALL | RE_ENGAGE |
| SEARCH | SEARCH |
| SHARE | SHARE |
| SPEND_CREDITS | SPENT_CREDITS |
| UNLOCK_ACHIEVEMENT | ACHIEVEMENT_UNLOCKED |
| VIEW_ITEM | CONTENT_VIEW |
Data limitations
Branch purges X Ads last-attributed data after 60 days. After this period, attribution data for X Ads conversions will no longer be available in exports or the Branch platform.
To configure your Branch time zone setting, navigate to Configuration > App Settings > General.
Troubleshooting
Connection fails with "Another MMP is already configured" error
This error means another mobile measurement partner is still configured in your X Ads account. Contact the X Ads team to remove the existing MMP configuration, or contact your previous measurement provider to remove the past X tags associated with your ad account. Once removed, retry the connection in Branch.
Ad account is not appearing during setup
If an ad account is not visible during the connection flow, check the following:
- Confirm that your X Ads user account has permissions to configure the ad account.
- Confirm that your app has an iOS App Store ID or Android Package Name configured in Branch Link Settings. X Ads only shows accounts for apps that are properly configured.
"Missing app event tags" error when enabling the integration
If you see a "Missing app event tags" error, go through the onboarding flow in Branch again from Configuration > Ad Partners > Twitter.
Reporting discrepancies between Branch and X Ads
Two common causes of discrepancies:
- Last-touch attribution model: X Ads claims all conversions within its attribution window, regardless of other ad interactions. Because Branch attributes to the last partner to interact with the user, discrepancies of 10–30% are typical.
- User data sharing opt-outs: X will still attribute conversions in its own reporting, but only shares conversion data with Branch if the user has allowed data sharing in their X settings. This can result in up to 50% discrepancies depending on user settings.
Additional resources
For more information on the X Ads integration and related topics, see the following articles: