Branch

Send conversion and engagement events to Branch server-to-server for mobile attribution, deep linking, and cross-platform conversion tracking.

⚠️

This blueprint is currently alpha — schema and behaviour may change before GA.

Prerequisites

Before configuring Branch in Signal, you need a Branch account, an app registered in the Branch dashboard, and your Branch Key and Branch Secret.

Get your Branch credentials

Step 1: Create a Branch account

Go to branch.io and sign up or sign in.
Complete the onboarding wizard and create a new app if you do not already have one.

Step 2: Find your Branch Key and Branch Secret

In the Branch dashboard, open Account Settings > Profile.
Locate the App section.
Copy the Branch Key (live key, format key_live_xxxxxxxxxx).
Click Show Secret and copy the Branch Secret.

⚠️

The Branch Secret authenticates server-to-server event delivery. Store it in your secrets manager — leaking it would let anyone post events to your Branch app.

Step 3: Configure your event taxonomy

In the Branch dashboard, open Data Feeds > Custom Events (or Liveview).
Confirm that the standard commerce events (PURCHASE, ADD_TO_CART, VIEW_ITEM, etc.) are enabled.
If you use custom event names, create them in Branch before sending — Branch will accept unknown names but they won’t appear in standard reports. [verify with current vendor docs]

Configure the integration in Signal

Configuration Fields

Field	Required	Description
`branch_key`	Yes	Your Branch live key (e.g. `key_live_xxxxxxxxxx`). Found in Account Settings > Profile.
`branch_secret`	Yes	Your Branch secret. Found in Account Settings > Profile (click “Show Secret”).

Management UI Setup

Go to Integrations in the sidebar.
Open the Integration Library tab.
Find Branch or filter by Attribution.
Click Install and enter your Branch Key and Branch Secret.
Click Install Integration.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/branch/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Branch",
    "variant": "retail",
    "config": {
      "branch_key": "key_live_xxxxxxxxxx",
      "branch_secret": "your_branch_secret"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

The Retail variant maps the following Datafly events to Branch commerce events:

Datafly Event	Branch Event	Notes
`Product Added`	`add_to_cart`	Product details as content items
`Order Completed`	`purchase`	Requires `revenue`, `currency`, `transaction_id`
Custom events	Passed through	Add the Branch event name in the blueprint event map

Identity

The default blueprint forwards the following identifiers to Branch:

Source	Branch field
`user_id`	`customer_id`
`context.ip`	`ip_address`
`context.user_agent`	`user_agent`

Branch matches events to its deep-link click graph using device identifiers (idfa, gps_adid, idfv) plus Branch’s own customer_event_alias. Pass these from your mobile app via the Datafly mobile SDK for accurate attribution.

Default consent category: advertising. Branch is a paid-media attribution destination — gate behind advertising consent in your CMP.

Verify it’s working

Trigger a test event from a test device or browser.
In the Signal Management UI, open your Branch integration and watch the Live Events stream.
In the Branch dashboard, open Liveview — events appear in real-time.
Confirm 200 responses in Signal’s Live Events log.

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Invalid Branch Key or Secret	Re-copy both from Account Settings > Profile and update Signal.
Events not joining click attribution	Missing device identifier	Capture `idfa`, `idfv`, or `gps_adid` from the Branch SDK and pass them via the Datafly mobile SDK.
Custom event names not appearing in reports	Event not pre-registered in Branch	Create the custom event in Branch’s dashboard before sending. [verify with current vendor docs]
Revenue not tracked	Missing `revenue` or `currency`	Ensure `Order Completed` events include `total`/`revenue` and `currency`.

Blueprint

The Branch blueprint version is 0.1.0 (alpha). It ships with a Retail variant covering add_to_cart and purchase events.