Desktop & Over the Top (OTT) Attribution

  • Published on Mar 4, 2025

Overview

Branch supports server-to-server (S2S) measurement for desktop and all of the popular over-the-top (OTT) platforms.

This document outlines how to send sessions and conversion events. These are separate, because sessions are fundamentally different from conversion events. The response from a request to Branch to log a session may include deep link data. This can be used to deep link the user to content, including the “deferred deep linking” scenario where a user clicked a link, then installed the app and opened it.

We use Roku as the basis for this guide, but applies to other OTT solutions. We provide an example request (curl), then we discuss each parameter in the request. For specific parameters, we provide tables showing how to change the request based on the platform (e.g. Amazon Fire TV, Apple TV, Samsung Smart TV).

Prerequisites

  • App is setup in the Branch dashboard with default link redirects, your app.link domains, a URI scheme, Universal Links.

  • Make sure you have access to your API & Secret keys.

  • Complete the in-app setup steps.

Session Measurement

A session measurement request should be made to the /v1/open endpoint every time the app is opened. The response should be parsed and a few of the values should be used on subsequent requests (i.e. randomized_device_token, randomized_bundle_token).

Session Request Parameters

Parameter

Type

Definition

branch_key

String

Your branch key, provided upon the time of dashboard creation.

branch_secret

String

Your branch secret, provided upon the time of dashboard creation.

server_to_server

Boolean

Hard code this into the request as true.

app_version

String

Your app’s semantic version ID.

os

String

See platform specific key-value section.

os_version

String

OS semantic version ID.

retryNumber

Integer

Default to 0. If retrying a request, then set this to 1 (first retry) or 2 (second retry).

brand

String

Brand of device.

model

String

Model of device.

screen_height

Integer

Height of the screen.

screen_width

Integer

Width of the screen.

ad_tracking_enabled

Boolean

Ensure that this is passed so that Branch can utilize this flag.

advertising_ids

Map of String → String

Should include the appropriate key for the device, and then the value of that advertising ID. See [platform specific key-value section(#session-platform-specific-key-values).

launch_options

Roku ONLY
Map of query params on the launch or input request, as well as other metadata that may be passed to the Roku app as part of these commands.
Example: the following command is issued to your app:
curl -d '' 'http://192.168.0.1:8060/launch/dev?contentId=1234&mediaType=movie'

randomized_device_token

String

On initial request (i.e. install), omit this key. Will be returned in the first response (e.g. "randomized_device_token": "123456789123456789"). Then send this up on subsequent requests.

server_to_server_identity

Boolean

Hard code this into the request as true. This generates the randomized_bundle_token for the s2s requests and returns in the response. This needs to be accompanied by identity below.

identity

String

Only works with the server_to_server_identity

This is mapped and set as the developer_id when making the s2s call. Example - "test_user_01”

link_identifier

String

When a URI opens the app, check for a link_click_id
query, and populate with that value (if missing, do not include in request)
Ex. yourapp://open?link_click_id=823569794275788167

Session Platform-specific Key Values

mac_OS

  • os: mac_OS

  • id: MAC address (Media Access Control)

    • example: "mac_address" : "88:66:5a:2f:81:fa"

WINDOWS

  • os: WINDOWS

  • advertising_ids: windows_advertising_id

    • example: "windows_advertising_id": "ea31e5e0"

  • id: MAC address (Media Access Control)

    • example:  "mac_address" : "00:1A:C2:7B:00:47"

tv_OS

  • os: tv_OS

  • advertising_ids: idfa

    • example: "idfa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

ROKU

  • os: ROKU

  • advertising_ids: roku_rida

    • example: "roku_rida": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

SAMSUNG

  • os: SAMSUNG

  • advertising_ids: samsung_ifa

    • example: "samsung_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

LG

  • os: LG

  • advertising_ids: lg_ifa

    • example: "lg_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

PANASONIC

  • os: PANASONIC

  • advertising_ids: panasonic_ifa

    • example: "panasonic_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

XBOX

  • os: XBOX

  • advertising_ids: xbox_msai

    • example: "xbox_msai": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

Example Request

curl -d '{
  "branch_key": "key_live_YOUR_KEY_HERE",
  "app_version": "1.0.1",
  "os": "ROKU",
  "os_version": "10.0",
  "retryNumber": 0,
  "brand": "Roku",
  "model": "4200X",
  "sdk": "roku",
  "sdk_version": "1.0.0",
  "screen_height": 1334,
  "screen_width": 750,
  "ad_tracking_enabled": true,
  "advertising_ids": {
    "roku_rida": "00000000-0000-0000-0000-000000000123"
  },
  "launch_options": {
    "contentID": "1234",
    "instant_on_run_mode": "foreground",
    "lastExitOrTerminationReason": "EXIT_UNKNOWN",
    "mediaType": "movie",
    "source": "external-control",
    "splashTime": "1500"
  },
  "randomized_device_token": "123456789123456789",
  "randomized_bundle_token": "987654321987654321"
}' "https://api2.branch.io/v1/open"

Example Response

{
  "data": "{\"+clicked_branch_link\":true,\"+is_first_session\":false,\"contentID\":\"1234\",\"mediaType\":\"movie\"}",
  "randomized_device_token": "123456789123456789",
  "randomized_bundle_token": "987654321987654321",
  "session_id": "685187705776489500"
}

NOTE: The deep link data is located inside the object data. It includes +clicked_branch_link: true as well as the link data.

Conversion Event Measurement

Conversion events include anything beyond sessions. They include signups, content views, purchases, and the like.

For Standard Events, please make requests to: /v2/event/standard

If you want to track an event not on this list, then you can track a Custom Event. These will not be nicely mapped to 3rd party event names, so this should be a fallback if there is no good Standard Event available.

Branch Standard Events

For a full list of Branch Standard Events, please see this document.

For Custom Events, please make requests to: /v2/event/custom

Conversion Event Request Parameters

Parameter

Type

Definition

name

String

Should be a Standard Event name if using /v2/event/standard. Otherwise can be a custom event name (any string) if using /v2/event/custom.

customer_event_alias

String

Can be any string.

branch_key

String

Your branch key, provided upon the time of dashboard creation.

REQUIRED

user_data.developer_identity

String

Your ID for a user.

user_data.app_version

String

Your app’s semantic version ID.

user_data.os

String

See platform specific key-value section.

user_data.os_version

String

OS semantic version ID.

user_data.brand

String

Brand of device.

user_data.model

String

Model of device.

user_data.screen_height

Integer

Height of the screen.

user_data.screen_width

Integer

Width of the screen.

user_data.environment

String

See platform specific key-value section.

user_data.limit_ad_tracking

Boolean

Ensure that this is passed so that Branch can utilize this flag. Inverse of /v1/open -> ad_tracking_enabled

user_data.advertising_ids

Map of String → string

Should include the appropriate key for the device, and then the value of that advertising ID. See platform specific key-value section.

user_data.randomized_device_token

String

On initial request (i.e. install), omit this key. Will be returned in the first response (e.g. "randomized_device_token": "123456789123456789"). Then send this up on subsequent requests.

event_data.transaction_id

String

Your ID for the event's transaction.

event_data.currency

String (enum)

ISO-4217 Currency Codes Only

event_data.revenue

Double / float

The revenue amount of said transaction.

retryNumber

Integer

Default to 0. If retrying a request, then set this to 1 (first retry) or 2 (second retry).

Conversion Event Platform-Specific Key Values

mac_OS

  • user_data.os: mac_OS

  • user_data.environment: DESKTOP_APP

  • id: MAC address (Media Access Control)

    • example: "mac_address" : "88:66:5a:2f:81:fa"

WINDOWS

  • user_data.os: WINDOWS

  • user_data.environment: DESKTOP_APP

  • user_data.advertising_ids: windows_advertising_id

    • example: "windows_advertising_id": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

  • id: MAC address (Media Access Control)

    • example:  "mac_address" : "00:1A:C2:7B:00:47"

ROKU

  • user_data.os: ROKU

  • user_data.environment: TV_APP

  • user_data.advertising_ids: roku_rida

    • example: "roku_rida": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

SAMSUNG

  • user_data.os: SAMSUNG

  • user_data.environment: TV_APP

  • user_data.advertising_ids: samsung_ifa

    • example: "samsung_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

LG

  • user_data.os: LG

  • user_data.environment: TV_APP

  • user_data.advertising_ids: lg_ifa

    • example: "lg_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

PANASONIC

  • user_data.os: PANASONIC

  • user_data.environment: TV_APP

  • user_data.advertising_ids: panasonic_ifa

    • example: "panasonic_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

XBOX

  • user_data.os: XBOX

  • user_data.environment: TV_APP

  • user_data.advertising_ids: xbox_msai

    • example: "xbox_msai": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

Sample Request

curl -d '{
  "name": "PURCHASE",
  "customer_event_alias": "purchase 5 tokens",
  "branch_key": "key_live_00000000000000",
  "user_data": {
    "developer_identity": "user123",
    "app_version": "1.0.1",
    "os": "ROKU",
    "os_version": "10.0",
    "brand": "Roku",
    "model": "4200X",
    "sdk": "roku",
    "sdk_version": "1.0.0",
    "screen_height": 1334,
    "screen_width": 750,
    "environment": "TV_APP",
    "limit_ad_tracking": false,
    "advertising_ids": {
      "roku_rida": "00000000-0000-0000-0000-000000000123"
    },
    "randomized_device_token": "123456789123456789"
  },
  "event_data": {
    "transaction_id": "foobar",
    "currency": "USD",
    "revenue": 100
  },
  "retryNumber": 0
}' "https://api2.branch.io/v2/event/standard"

Example Response

You do not need to examine the response body. Simply look for a 200 HTTP status code. Non-2xx status codes indicate an error.