Skip to main content

Branch integration plan

Last updated 10/03/2026
tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary​

Interface overview​

InterfaceTypeGranularityAttributionCostRevenueImpressionsClicksConversions
WebhooksCallbackUser level✅✅

Branch provides Webhooks to send back user-level data. You can pass information such as channel attribution into AE user properties, or write the callback data as events

Before you start connecting Branch data, make sure you have read the AE system user identification rules and understand how AE identifies a user by #distinct_id and #account_id

Integration process​

  1. Integrate the Branch SDK and the AE SDK, and set the AE system's distinct ID and account ID in the Branch SDK
  2. Log in to the AE backend, go to the Third-party Integration module, add a Branch Webhook callback plan, and complete the related configuration
  3. Configure Webhooks in the Branch dashboard and pass in the AE callback link
  4. Check whether the AE system receives the data successfully, and build reports

1. Client SDK reporting​

If you choose to report data with the client SDK, first integrate the Branch SDK and the AE SDK into your app. Then use the Branch SDK method for setting initialization metadata parameters to set the AE system's user identification IDs (the account ID and distinct ID) in the Branch SDK. Branch's callback data then carries these ID fields, so Branch data can be associated with AE data.

1.1 Option 1 (automatic integration)​

  • If you integrate the Android or iOS SDK:

  • If you integrate Unity SDK 2.4.0 or later, or Unreal SDK 1.5.0 or later, you can use this option directly

tip

Note that the AE SDK must be initialized before the Branch SDK, and the code that enables automatic integration must be called immediately after the Branch SDK is initialized. Follow these steps:

  1. Initialize the AE SDK.
  2. Initialize the Branch SDK.
  3. Call enableThirdPartySharing to set the distinct ID automatically.

The following are code samples for the SDK on each platform:

// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Initialize the Branch SDK
//  ...
// 3. Call the enableThirdPartySharing API to set ta_distinct_id in Branch events
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.BRANCH);
// 4. After registration or character creation, call login to set the account ID, then sync the data again (optional)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.BRANCH);

This option works by automatically calling Branch's setRequestMetadata method internally and passing in ta_distinct_id and ta_account_id.

1.2 Option 2 (manual integration)​

For manual integration, you need to use the setRequestMetadata() API in the Branch SDK to set the distinct ID and account ID of the AE project.

tip

Note that the AE SDK must be initialized before the Branch SDK. Follow these steps:

  1. Initialize the AE SDK.
  2. Initialize the Branch SDK.
  3. Call setRequestMetadata to set the distinct ID.
// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = TDAnalytics.getDistinctId();
// 3. Initialize the Branch SDK
//  ...
// 4. Set the distinct ID in the events collected by Branch
Branch.getInstance().setRequestMetadata("ta_distinct_id", distinctId);

// 5. After registration or character creation, call login to set the account ID, then sync the data again (optional)
String accountId = "account_id";
TDAnalytics.login(accountId);
Branch.getInstance().setRequestMetadata("ta_account_id", accountId);

In Branch's Webhook callback data, ta_distinct_id and ta_account_id correspond to the distinct ID and account ID of the AE system.

warning

Call setRequestMetadata() to set the metadata parameters immediately after the Branch SDK finishes initializing, to avoid missing metadata parameters in some Branch data. If the data still lacks the metadata parameters, or the user identification fields can't be obtained immediately after initialization, you can use Branch's Delay Session Initialization method to delay session initialization and set the metadata during the delay, so that all data carries the user identification fields.

2. Plan configuration​

After completing the SDK configuration, log in to the AE system backend and configure Branch in the Third-party Integration module. The image below shows the Branch configuration page:

2.1 User identification fields​

Because Branch Webhook data is user-level data, you need to set user identification rules for it, that is, the AE system's user identification IDs set in the Branch SDK. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.

If you configured the client SDK as described in the previous step of this document, use the following configuration:

  • Field associated with the account ID: ta_account_id
  • Field associated with the distinct ID: ta_distinct_id

2.2 Event Data Configuration​

After you turn on the Event Data Configuration switch, all data sent back by Branch is written to the event table. We recommend that you enable event data ingestion.

2.3 User Properties Configuration​

By default, the AE system automatically writes the attribution fields in Branch callback data to standardized user properties. The following are the fields written to user properties and their meanings:

Branch fieldUser property name in AEDescription
query.channelte_ads_object.media_sourceChannel
query.campaignte_ads_object.campaign_nameCampaign
query.ad_set_namete_ads_object.ad_group_nameAd group
query.creative_namete_ads_object.ad_nameAd creative

To make changes, click Configure Rules to go to the ingestion rule configuration page, as shown below

You can change the Integration method of user properties. The default is user_setOnce, which keeps only the first reported information.

For Source Property, add the query. prefix before the ingested field name

Click the Property Mapping button to add fields to write to user properties. You can also click the Rule button on the left to add a new set of rules.

To turn off user property ingestion, stop all rules:

2.4 Configuration​

In the Configuration module, you can control the detailed settings of data pulling, such as the event name after ingestion

The content of the configuration is a JSON, which you can customize as follows:

ModuleNameDescription
sink_eventevent_mappingEvent name after ingestion; customizable. The key is the event name in Branch callback data, and the value is the event name after ingestion

2.5 End Point​

If you have configured system-level and project-level receiver URLs, the following link is shown

If no address is shown here, go to Project Settings → Settings → Implementation in the upper-right menu to configure the public network address. You can also click the TE Receiver Host URL link in the tip bar on the configuration page to go there. This address is the receiver URL configured in the AE SDK. After configuring it, return to End Point on the Branch Webhook configuration page and copy the endpoint address.

2.5.1 Custom macros​

The Branch Webhook callback URL contains a structure called a macro, written as ${(macro_name)!}. You can think of a macro as a placeholder: when the data that Branch sends back contains a field that corresponds to a macro, Branch fills the value of that field in where the macro is. Taking ${(last_attributed_touch_data.~campaign)!} as an example, when Branch sends back data, it fills in the Campaign value where the macro is in the callback URL.

Replace the beginning of the following URL with the endpoint address you just obtained, and copy the resulting callback URL. You'll need to enter it in the Branch dashboard later:

https://{End Point}?branch_id=${(id)!}&campaign=${(last_attributed_touch_data.~campaign)!}&campaign_id=${(last_attributed_touch_data.~campaign_id)!}&campaign_type=${(last_attributed_touch_data.~campaign_type)!}&customer_campaign=${(last_attributed_touch_data.~customer_campaign)!}&channel=${(last_attributed_touch_data.~channel)!}&feature=${(last_attributed_touch_data.~feature)!}&stage=${(last_attributed_touch_data.~stage)!}&tags=${(last_attributed_touch_data.~tags)!}&advertising_partner_name=${(last_attributed_touch_data.~advertising_partner_name)!}&advertising_partner_id=${(last_attributed_touch_data.~advertising_partner_id)!}&secondary_publisher=${(last_attributed_touch_data.~secondary_publisher)!}&secondary_publisher_id=${(last_attributed_touch_data.~secondary_publisher_id)!}&customer_secondary_publisher=${(last_attributed_touch_data.~customer_secondary_publisher)!}&creative_name=${(last_attributed_touch_data.~creative_name)!}&creative_id=${(last_attributed_touch_data.~creative_id)!}&ad_set_name=${(last_attributed_touch_data.~ad_set_name)!}&ad_set_id=${(last_attributed_touch_data.~ad_set_id)!}&customer_ad_set_name=${(last_attributed_touch_data.~customer_ad_set_name)!}&ad_name=${(last_attributed_touch_data.~ad_name)!}&ad_id=${(last_attributed_touch_data.~ad_id)!}&customer_ad_name=${(last_attributed_touch_data.~customer_ad_name)!}&keyword=${(last_attributed_touch_data.~keyword)!}&keyword_id=${(last_attributed_touch_data.~keyword_id)!}&customer_keyword=${(last_attributed_touch_data.~customer_keyword)!}&branch_ad_format=${(last_attributed_touch_data.~branch_ad_format)!}&technology_partner=${(last_attributed_touch_data.~technology_partner)!}&banner_dimensions=${(last_attributed_touch_data.~banner_dimensions)!}&placement=${(last_attributed_touch_data.~placement)!}&placement_id=${(last_attributed_touch_data.~placement_id)!}&customer_placement=${(last_attributed_touch_data.~customer_placement)!}&sub_site_name=${(last_attributed_touch_data.~sub_site_name)!}&customer_sub_site_name=${(last_attributed_touch_data.~customer_sub_site_name)!}&agency=${(last_attributed_touch_data.~agency)!}&agency_id=${(last_attributed_touch_data.~agency_id)!}&ta_distinct_id=${(custom_data.ta_distinct_id)!}&ta_account_id=${(custom_data.ta_account_id)!}

2.6 Save the plan​

After completing the configuration, click the Save button in the upper-right corner to save the plan.

3. Configure the Branch Webhook callback​

After saving the plan, log in to the Branch dashboard, go to the Data Feeds page, and add a new Webhook on the WEBHOOKS tab:

Configure the Webhook link and details. You need to fill in three parts, from top to bottom and left to right:

  1. Send a webhook to: Enter the endpoint address you got from the AE backend, with the required custom macros added, here
  2. using a ...: Select the POST method
  3. every time users trigger the event ...: If you report with the client SDK, you can select the INSTALL event

Click Save Rule to save the rule. This completes the Branch callback configuration

warning

Notes on install events after iOS 14.5:

When an install is attributed to a paid ad, a second install event is triggered after the user opts in to ATT

Opting in affects your final install count. We recommend that you use a different identifier (such as IDFV) to deduplicate install events in your internal systems (you can do this with the secondary development tools in the AE system).

4. Data ingestion​

4.1 Event ingestion rules​

  • The event_timestamp field in the data is used as the event's #event_time

  • The event name of the data comes from sink_event.event_mapping in the configuration. By default:

    • Install: branch_install
    • Other events not listed in sink_event.event_mapping: the branch_ prefix is added before the name field

  • All properties corresponding to the other macros in the callback URL are ingested

The following is the list of properties that Branch sends back when you use the callback URL provided in this document:

Ingested nameDescription
nameBranch event name
event_timestampData time
campaignAttributed campaign name
campaign_idAttributed campaign ID
campaign_typeAttributed campaign type (from Google AAP attribution)
customer_campaignCustom attributed campaign name
channelAttributed channel name
featureAttributed feature, such as "paid advertising"
stageStage
tagsAttributed tags
advertising_partner_nameReadable advertising partner name
advertising_partner_idAdvertising Partner ID
secondary_publisherSecondary publisher name
secondary_publisher_idSecondary Publisher ID
customer_secondary_publisherCustom secondary publisher ID
creative_nameAttributed creative name
creative_idAttributed creative ID
ad_set_nameAttributed ad set name
ad_set_idAttributed ad set ID
customer_ad_set_nameCustom ad set name
ad_nameAttributed ad name
ad_idAttributed ad ID
customer_ad_nameCustom ad name
keywordAttributed keyword
keyword_idAttributed keyword ID
customer_keywordCustom keyword
branch_ad_formatAd type, such as Search, Display, Product Ad, App only
technology_partnerThird-party technology partner
banner_dimensionsBanner dimensions
placementAttributed placement
placement_idAttributed placement ID
customer_placementCustom placement
sub_site_nameSub-site name
customer_sub_site_nameCustom sub-site name
agencyAgency name
agency_idAgency ID
ta_distinct_idDistinct ID of the AE system
ta_account_idAccount ID of the AE system

4.2 Standardized fields​

The AE system standardizes some fields in Branch Webhook callback data reports

Original fieldStandardized fieldDescription
campaignte_ads_object.campaign_nameCampaign name
campaign_idte_ads_object.campaign_idCampaign ID
ad_set_namete_ads_object.ad_group_nameAd group name, or the Unit name for monetization ads
ad_set_idte_ads_object.ad_group_idAd group ID, or the Unit ID for monetization ads
ad_namete_ads_object.ad_nameAd name
ad_idte_ads_object.ad_idAd ID
placementte_ads_object.placementAd placement
channelte_ads_object.media_sourceMedia source
Was this page helpful?
On this page