> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/attribution/branchio.md).

# Branch

[Branch.io](https://branch.io) is an industry leader in cross-platform attribution, mobile app measurement, and deep linking. Many top-ranking apps use Branch to increase their performance and revenue through better performance and engagement.

RudderStack supports sending events from RudderStack SDKs to Branch through our data plane via the S2S (Server to Server) connection mode. You can also opt for the device mode as well for Android and iOS. Branch SDK is wrapped inside Rudder SDK in case of device mode.

**Find the open-source transformer code for this destination in our**[**GitHub repo**](https://github.com/rudderlabs/rudder-transformer/tree/master/v0/destinations/branch)**.**

## Getting Started

Before getting started, please determine whether the platform you are sending your event data from is supported. Refer to the following table for more the supported source types and connection modes:

| **Connection Mode** | **Web** | **Mobile**    | **Server** |
| ------------------- | ------- | ------------- | ---------- |
| **Device mode**     | -       | **Supported** | -          |
| **Cloud mode**      | -       | **Supported** | -          |

To know more about the difference between Cloud mode and Device mode in RudderStack, read the [RudderStack connection modes](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.

In order to start sending data to Branch, you will first need to add it as a destination to the source from which you are sending the event data.

* Once you have added the source, you will need to register on Branch and follow the required steps to complete the set up.
* You should then be able to access the Branch key from the settings page of your Branch [dashboard](https://dashboard.branch.io/#/settings).
* Enter your Branch key to complete the destination configuration as shown:

![](/files/uOeKYYwhPF2mSH8rZlba)BranchIO Dashboard Settings

Please note that RudderStack does not support sending data to Branch on both device or cloud mode for the web.

## Adding device mode integration

Depending on the platform of integration follow the steps below to integrate with Device-mode.

iOS Android

* Open the `Podfile` of your project and add the following line

  ```ruby
  pod 'Rudder-Branch', '0.1.3'
  ```

  followed by

  ```bash
  $ pod install
  ```
* Finally change the SDK initialization with the following

  ```objectivec
  RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
  [builder withDataPlaneUrl:<DATA_PLANE_URL>];
  [builder withFactory:[RudderBranchFactory instance]];
  [builder withLoglevel:RudderLogLevelDebug];
  [RudderClient getInstance:<WRITE_KEY> config:[builder build]];
  ```

Your Android project must be on **version 5.0 (API level 21) or higher** for RudderStack to be able to send events to Branch.

Once confirmed, follow these steps to add Branch to your Android project:

* Open your `app/build.gradle` (Module: app) file, add the following

  ```groovy
  repositories {
      mavenCentral()
  }
  ```
* Add the following under `dependencies` section

  ```groovy
  implementation 'com.rudderstack.android.sdk:core:1.0.1'
  implementation 'com.rudderstack.android.integration:branch:0.1.3'

  // branch SDK requirements
  implementation 'io.branch.sdk.android:library:4.3.2'
  implementation'com.android.installreferrer:installreferrer:1.1.2'
  implementation 'com.google.firebase:firebase-appindexing:19.1.0'
  implementation 'com.google.android.gms:play-services-ads:16+'
  ```
* Finally change the initialization of the SDK with the following

  ```kotlin
  val rudderClient: RudderClient = RudderClient.getInstance(
      this,
      <WRITE_KEY>,
      RudderConfig.Builder()
          .withDataPlaneUrl(<DATA_PLANE_URL>)
          .withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
          .withFactory(BranchIntegrationFactory.FACTORY)
          .build()
  )
  ```

Now follow the instructions below to send events to Branch.

## Identify

The `identify` call associates a user to their actions and also captures the traits associated with that user. Some of captured information includes a unique user ID, as well as optional traits such as name, email, IP address, etc.

A sample identify call captured from the RudderStack iOS SDK would look like the following:

```objectivec
[[RudderClient sharedInstance] identify:@"developer_user_id"
                                 traits:@{@"foo": @"bar", @"foo1": @"bar1"}];
```

Ideally, this call is made when the user registers to the app for the first time, or after the user logs into the app or updates their information.

## Track

The `track` call captures all the activities that the user performs, along with any other properties that are associated with those activities. Each of these activities or actions is considered by RudderStack as an **event**.

A sample `track` call looks like the following:

```objectivec
[[RudderClient sharedInstance] track:@"test_event"
                          properties:@{@"key":@"value", @"foo": @"bar"}]
```

For example, consider the following code snippet for a `track` event `Product Added` from your JavaScript SDK:

```javascript
rudderanalytics.track('Product Added', {
  cart_id: '1234',
  products: [
    {
       product_id: 'mobi1',
       name: "mobile name",
       brand: "brand name",
       variant: "4gb/8gb",
       price: "750$",
       quantity: "1",
       description: "Mobile phone description goes here",
    },
    {
       product_id: 'mobi2',
       name: "mobile name",
       brand: "brand name",
       variant: "16gb/32gb",
       price: "1000$",
       quantity: "1",
       description: "Mobile phone description goes here",
    }
  ]
});
```

All the trackable events in RudderStack are divided into three major Branch event categories:

* Commerce Events
* Content Events
* Lifecycle Events

The following table lists the mapping between the accepted names of the E-commerce events:

| RudderStack Event           | Branch Event        |
| --------------------------- | ------------------- |
| `Product Added`             | `ADD_TO_CART`       |
| `Product Added to Wishlist` | `ADD_TO_WISHLIST`   |
| `Cart Viewed`               | `VIEW_CART`         |
| `Checkout Started`          | `INITIATE_PURCHASE` |
| `Payment Info Entered`      | `ADD_PAYMENT_INFO`  |
| `Order Completed`           | `ADD_PAYMENT_INFO`  |
| `Spend Credits`             | `SPEND_CREDITS`     |
| `Promotion Viewed`          | `VIEW_AD`           |
| `Promotion Clicked`         | `CLICK_AD`          |
| `Checkout Started`          | `PURCHASE`          |
| `Order Completed`           | `PURCHASE`          |
| `Reserve`                   | `RESERVE`           |

RudderStack also maps the `Spend Credits` event to Branch's `SPEND_CREDITS`, although it is not directly a part of the E-commerce Events.

The following table lists the mapping between the accepted names of the Content events:

| RudderStack Event     | Branch Event      |
| --------------------- | ----------------- |
| `Products Searched`   | `SEARCH`          |
| `Product Viewed`      | `VIEW_ITEM`       |
| `Product List Viewed` | `VIEW_ITEMS`      |
| `Product Reviewed`    | `RATE`            |
| `Product Shared`      | `SHARE`           |
| `Initiate Stream`     | `INITIATE_STREAM` |
| `Complete Stream`     | `COMPLETE_STREAM` |

The above mentioned events are a part of the RudderStack Commerce events, but are mapped to Branch's Content Events.

RudderStack also supports mapping the following events even though they are not explicitly a part of the RudderStack Lifecycle Events:

| RudderStack Event       | Branch Event            |
| ----------------------- | ----------------------- |
| `Complete Registration` | `COMPLETE_REGISTRATION` |
| `Complete Tutorial`     | `COMPLETE_TUTORIAL`     |
| `Achieve Level`         | `ACHIEVE_LEVEL`         |
| `Unlock Achievement`    | `UNLOCK_ACHIEVEMENT`    |
| `Invite`                | `INVITE`                |
| `Login`                 | `LOGIN`                 |
| `Start Trial`           | `START_TRIAL`           |
| `Subscribe`             | `SUBSCRIBE`             |

The following table lists the mapping of the accepted property keys common to all events:

| RudderStack Property Key | Branch Property Key     |
| ------------------------ | ----------------------- |
| `title`                  | `$og_title`             |
| `description`            | `$og_description`       |
| `image_url`              | `$og_image_url`         |
| `canonical_identifier`   | `$canonical_identifier` |
| `publicly_indexable`     | `$publicly_indexable`   |
| `price`                  | `$price`                |
| `locally_indexable`      | `$locally_indexable`    |
| `quantity`               | `$quantity`             |
| `sku`                    | `$sku`                  |
| `name`                   | `$product_name`         |
| `brand`                  | `$product_brand`        |
| `category`               | `$product_category`     |
| `variant`                | `$product_variant`      |
| `rating_average`         | `$rating_average`       |
| `rating_count`           | `$rating_count`         |
| `rating_max`             | `$rating_max`           |
| `creating_timestamp`     | `$creation_timestamp`   |
| `exp_date`               | `$exp_date`             |
| `keywords`               | `$keywords`             |
| `address_street`         | `$address_street`       |
| `address_city`           | `$address_city`         |
| `address_region`         | `$address_region`       |
| `address_country`        | `$address_country`      |
| `address_postal_code`    | `$address_postal_code`  |
| `latitude`               | `$latitude`             |
| `longitude`              | `$longitude`            |
| `image_captions`         | `$image_captions`       |
| `condition`              | `$condition`            |

## FAQs

### Where can I get the Branch Key from?

You can retrieve the Branch key from the settings page of the [Branch dashboard](https://dashboard.branch.io/#/settings). For more information, please check the [Getting Started](https://rudderstack.com/docs/destinations/attribution/branchio#getting-started) section above.

## Contact Us

For queries on any of the sections covered in this guide, you can [**contact us**](mailto:%20docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/attribution/branchio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.