Overview

Sending events from Segment to Branch will allow you to attribute downstream conversions like purchases across web and app to Branch link clicks. Events imported from Segment to Branch will be available wherever you can normally use events within Branch, including dashboard visualizations, Data Feeds, Ads Postbacks, Journeys targeting, Liveview, and more.

This guide walks through the server-side integration for data import from Segment to Branch. For data export from Branch to Segment, see the Segment (Export) Configuration (New) guide.

How does it work?

Once the Branch SDK is integrated into an app, Branch can detect which Branch Links are leading to installs, re-opens, and users' actions. Enabling this integration and sending your events to Branch will allow Branch to enhance your Segment data with Branch data.

Branch events imported from Segment

Branch will import events that are not auto-tracked with the Branch SDKs. This includes commerce, content, user lifecycle, and custom events, and excludes events like clicks and installs. See the full list of supported events and associated mappings in Supported events. Branch will only import events that can be tied to a user.

Avoid Duplicate Data

To avoid duplicate data, you should either track conversion events directly with Branch or track events with Segment and then enable import to Branch, not both. Branch will warn you if you try to import events to Branch that you are already tracking.

Branch will only import events from Segment that are not already auto-tracked with the Branch SDK. This means that events like click and install cannot be imported. The following outlines how Segment events are mapped to Branch events, and which will be imported to Branch:

Segment Event	Branch Event	Branch Event Category	Imported
Product Added	Add To Cart	Commerce Event	Yes
Product Added to Wishlist	Add To Wishlist	Commerce Event	Yes
Cart Viewed	View Cart	Commerce Event	Yes
Payment Info Entered	Add Payment Info	Commerce Event	Yes
Checkout Started	Initiate Purchase	Commerce Event	Yes
Order Completed	Purchase	Commerce Event	Yes
use the Branch event name	Spend Credits	Commerce Event	Yes
Products Searched	Search	Content Event	Yes
Product Viewed	View Item	Content Event	Yes
Product List Viewed	View Items	Content Event	Yes
Product Reviewed	Rate	Content Event	Yes
Product Shared	Share	Content Event	Yes
use the Branch event name	Complete Registration	Lifecycle Event	Yes
use the Branch event name	Complete Tutorial	Lifecycle Event	Yes
use the Branch event name	Achieve Level	Lifecycle Event	Yes
use the Branch event name	Unlock Achievement	Lifecycle Event	Yes
any event name	Custom	Custom Event	Yes
Deep Link Clicked	Click	-	Not Supported
Install Attributed	Install	-	Not Supported
-	SMS Sent	-	Not Supported
-	Pageview	-	Not Supported
-	Web Session Start	-	Not Supported
-	Branch CTA View	-	Not Supported
-	Impression	-	Not Supported
Application Installed	-	-	Not Recommended
Application Opened	-	-	Not Recommended
Application Updated	-	-	Not Recommended
Application Backgrounded	-	-	Not Recommended
Application Crashed	-	-	Not Recommended
Application Uninstalled	-	-	Not Recommended
Push Notification Received	-	-	Not Recommended
Push Notification Tapped	-	-	Not Recommended
Push Notification Bounced	-	-	Not Recommended
Screen	-	-	Not Recommended
Page	-	-	Not Recommended
Identify	-	-	Not Recommended

Before you begin

To set up the Segment (import) integration, you first need to:

1. Admin access to your Branch account.
2. Have either the Engagement or Performance product enabled for your Branch account.
3. Implemented the Branch SDK into your mobile app (iOS | Android).
4. Implement the Segment SDK.
5. Admin access to your Segment account.

Enable Segment (import)

Complete the following steps to enable Segment (import):

1. Set up Branch

In Branch, go to Configuration > Integrations and select the Data tab. Search for Segment and select it to open its data partner page.

In the Import section, select the platforms you want to import events for, then toggle Import to Enabled and select Save:

• IOS_WEB
• IOS_APP
• ANDROID_WEB
• ANDROID_APP
• DESKTOP_WEB
• ROBOTS
• OTHER

Note

Only Segment events mapping to Branch v2 (commerce, content, user lifecycle, custom) are imported. Auto-tracked events like clicks or installs are excluded.

2. Set up Segment

Navigate to your Segment UI’s Destinations page.

1. Select Add Destination.
2. Search for Branch within the Destinations Catalog and confirm the Source you’d like to connect to.
3. Enter your Branch Key. This can be found in the Account Settings > App section of Branch.
4. Enter your Branch Secret. This can be found in the Account Settings > App section of Branch.

For server-side event import, you can ignore the SDK integration instructions.

Segment identifiers

The following describes the identifiers Branch uses for app and web events.

Identifiers for app events

Identifiers are required for events to be imported to Branch. You must include:

• context.device.advertisingId AND context.os.name AND context.os.version

OR

• context.device.id AND context.os.name AND context.os.version

Branch maps Segment's identifiers to the following:

Segment field	Branch field
userId	developer_identity
context.device.advertisingId	idfa or aaid
context.device.id	idfv or android_id
context.os.name	os
context.os.version	os_version

If using User ID with Segment, Branch will automatically map this to developer identity. See Developer Identity Instructions for ( iOS | Android ).

Check out Segment's User ID docs for more details.

Branch does not map Segment's anonymous ID to any field, and will not attribute logged out web events received from the server-to-server integration. Anonymous ID can still be attached to events.

Identifiers for web events

To attribute accurately on web, it is important to collect the Branch SDK's browser fingerprint and pass it to the Segment track function. Branch uses this along with the userAgent collected by the Segment SDK to identify the user's persona, platform, os, and other parameters. Collecting the browser fingerprint can be done with the following code snippet:

For Logged in web Events Only

Branch does not attribute logged out web events for Segment, even when passing an Anonymous ID.

const loadBranchAndGetFingerprint = new Promise(function(resolve, reject) {
  branch.init('BRANCH_KEY', {}, function(err, data) {
  branch.getBrowserFingerprintId(function(err, fingerprint) {  // fetch the browser fingerprint from the SDK
    if (!!err) {
      reject(err);
      return;
    }
    resolve({...data, fingerprint});
  });
  });
});

You can then pass it into the payload of the Segment track event:

loadBranchAndGetFingerprint.then(function(data) {
    const { fingerprint } = data;
    // Load the Segment SDK and initialize with key here

    // Segment track request
    analytics.track('Order Completed', {
        browser_fingerprint_id: fingerprint // add the browser fingerprint to the Segment track event
        //... Other event details ...
    })
});

Segment Track

The Branch integration supports some of the events tracked with Segment’s Track method. The track API call is how you record any actions your users perform, along with any properties that describe the action.

Each action is known as an event. Each event has a name, like Registered, and properties, for example a Registered event might have properties like plan or accountType. Here’s the payload of a typical track call with most common fields removed:

{
  "type": "track",
  "event": "Registered",
  "properties": {
    "plan": "Pro Annual",
    "accountType" : "Facebook"
  }
}

And here’s the corresponding Javascript event that would generate the above payload:

analytics.track("Registered", {
  plan: "Pro Annual",
  accountType: "Facebook"
});

See Segment's Track documentation for more details and examples.

3. Verify the integration

Once you have import turned on in both Segment and Branch, events should come through. You will see a green dot on the import card if Branch has seen events:

Branch imports events from Segment as commerce, user lifecycle, content, or custom events.

Using imported events

Events imported from Segment to Branch will be available wherever you can normally use events within Branch. This includes dashboard visualizations, Data Feeds (including Data Integrations, Query API, Webhooks, and Daily Export API), Ads postbacks, Journeys targeting, Liveview, and more.

Advanced

The following sections cover advanced configuration options.

Attaching anonymous ID to events

Events imported from Segment with anonymous ID attached will retain that value on the event, and will be available in the custom_data field if exported back out from Branch. To attach anonymous ID to events auto-tracked by Branch (installs, opens, etc.), follow the instructions in Segment (Export) Configuration (New).

Attribution for logged out users on web

Branch uses a custom, in-house identifier for logged out users on web. If you enable the server to server integration from Segment to Branch, you will not be able to attribute logged out web events from Segment to a campaign run with Branch. For this reason, you may want to track web events directly with the Branch web SDK, while still sending app events server to server from Segment. Branch allows you to then toggle web event import off to prevent duplicate data.