Segment (Import)

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, Universal 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, go here.

What events does Branch import?

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 here. Branch will only import events that can be tied to a user.

Setup

  1. Contact Branch to configure Branch to receive events from Segment. Please note that a subscription to Data Feeds is required to enable data import from Segment to Branch.
  2. Navigate to the Data Integrations page of the Branch dashboard.
    1. Select Segment from the menu on the left.
    2. Select the platforms you would like to import events from and click Save.
22122212
  1. Navigate to your your Segment UI’s Destinations page.
    1. Click on 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 the Branch dashboard.
    4. Enter your Branch Secret. This can be found in the Account Settings > App section of the Branch dashboard.

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

🚧

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.

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.

Supported events

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 EventBranch EventBranch Event CategoryImported
Product AddedAdd To CartCommerce EventYes
Product Added to WishlistAdd To WishlistCommerce EventYes
Cart ViewedView CartCommerce EventYes
Payment Info EnteredAdd Payment InfoCommerce EventYes
Checkout StartedInitiate PurchaseCommerce EventYes
Order CompletedPurchaseCommerce EventYes
use the Branch event nameSpend CreditsCommerce EventYes
Products SearchedSearchContent EventYes
Product ViewedView ItemContent EventYes
Product List ViewedView ItemsContent EventYes
Product ReviewedRateContent EventYes
Product SharedShareContent EventYes
use the Branch event nameComplete RegistrationLifecycle EventYes
use the Branch event nameComplete TutorialLifecycle EventYes
use the Branch event nameAchieve LevelLifecycle EventYes
use the Branch event nameUnlock AchievementLifecycle EventYes
any event nameCustomCustom EventYes
Deep Link ClickedClick-No
Install AttributedInstall-No
-SMS Sent-No
-Pageview-No
-Web Session Start-No
-Branch CTA View-No
-Impression-No
Application Installed--No
Application Opened--No
Application Updated--No
Application Backgrounded--No
Application Crashed--No
Application Uninstalled--No
Push Notification Received--No
Push Notification Tapped--No
Push Notification Bounced--No

Identifiers for app events

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

  • context.device.advertisingId AND context.os.name OR
  • context.device.id AND context.os.name OR

Branch maps Segment's identifiers to the following:

Segment fieldBranch field
userIddeveloper_identity
context.device.advertisingIdidfa or aaid
context.device.ididfv or android_id
context.os.nameos

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

In order 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 ...
    })
});

Validating 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:

501501

To see more information on the events that are coming in, you can look at events with origin SEGMENT in Liveview:

16961696

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), Universal Ads postbacks, Journeys targeting, Liveview and more.

Advanced

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 here.

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.

Filters