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

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

## Connection compatibility

{{< destination-config >}}

## Get started

Once you have confirmed that the source platform supports sending events to Branch, follow these steps:

1. From your [RudderStack dashboard](https://app.rudderstack.com/), add a source. Then, from the list of destinations, select **Branch Metrics**.
2. Assign a name to the destination and click **Continue**.

## Connection settings

To successfully set up Branch as a destination, you will need to configure the following settings:

- **Branch key**: Enter your Branch key from the **Settings** section in the [Branch dashboard](https://dashboard.branch.io/#/settings). For more information on obtaining this key, see [FAQ](#faq).
- **Map Your Events To Branch Events**: Use this setting to map your RudderStack events to specific Branch events from the dropdown. 

{{< info >}}
Note that:

- This setting is currently available in cloud mode only. 
- The mappings specified using this setting override the [default event mappings](#ecommerce-event-mapping) configured by RudderStack internally.
{{< /info >}}

{{< image src="images/event-stream-destinations/branch-event-mapping-ui.webp" alt="Branch event mapping setting" >}}

- **Client-side Events Filtering**: This setting lets you specify which events should be blocked or allowed to flow through to Branch. For more information on this setting, see the [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}) guide.
- **Consent management settings**: Configure the consent management settings for the specified source by choosing the **Consent management provider** from the dropdown and entering the relevant consent category IDs. See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) for more information on this feature.

## Adding device mode integration

Depending on your platform of integration, follow the below steps below to integrate Branch with your app.

{{< tabs tabTotal="3">}}
{{% tab tabName="iOS (Obj-C) — Legacy" %}}

1. Open the `Podfile` of your project and add the following line:

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

2. Run the `pod install` command.
3. Change the SDK initialization to 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]];
```

{{% /tab %}}
{{% tab tabName="iOS SDK v2 — Legacy" %}}
{{< warning >}}
This device mode integration is supported for Branch v1.41.0 and above.
{{< /warning >}}
Follow these steps to add Branch to your iOS project:

1. Install `RudderBranch` (available through [CocoaPods](https://cocoapods.org)) by adding the following line to your `Podfile`:

```ruby
pod 'RudderBranch', '~> 1.0.0'
```

2. Run the `pod install` command.
3. Then, import the SDK depending on your preferred platform:

```swift
import RudderBranch
```


```objectivec
@import RudderBranch;
```

4. Next, add the imports to your `AppDelegate` file under the `didFinishLaunchingWithOptions` method:


```swift
let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)

RSClient.sharedInstance().configure(with: config)
RSClient.sharedInstance().addDestination(RudderBranchDestination())
```

```objectivec
RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];

[[RSClient sharedInstance] configureWith:config];
[[RSClient sharedInstance] addDestination:[[RudderBranchDestination alloc] init]];
```

{{% /tab %}}
{{% tab tabName="Android (Java) — Legacy" %}}
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:

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


```groovy
repositories {
    mavenCentral()
}
```

2. Add the following under `dependencies` section:

```groovy
implementation 'com.rudderstack.android.sdk:core:[1.20.1, 2.0.0)'
implementation 'com.rudderstack.android.integration:branch:2.0.0'
```

3. If needed, add the following **optional** dependencies required by Branch in the `dependencies` section:

```groovy
// required if your app is in the Google Play Store (tip: avoid using bundled play services libs)
implementation 'com.google.android.gms:play-services-ads-identifier:17.1.0+'
// alternatively, use the following lib for getting the AAID
// implementation 'com.google.android.gms:play-services-ads:17.2.0'
// optional
// Chrome Tab matching (enables 100% guaranteed matching based on cookies)
implementation 'androidx.browser:browser:1.0.0'
// Replace above with the line below if you do not support androidx
// implementation 'com.android.support:customtabs:28.0.0'
```

4. Change the initialization of the SDK with the following:

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

{{% /tab %}}
{{< /tabs >}}

## Identify

The [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call associates a user to their actions and also captures the traits associated with that user.

A sample `identify` call captured from the RudderStack iOS (Obj-C) SDK is as shown:

```objectivec
[[RudderClient sharedInstance] identify:@"developer_user_id"];
```

{{< info >}}
You can call `identify` when the user registers to the app for the first time, logs into the app, or updates their information.
{{< /info >}}

## Track

The [`track`]({{< ref "event-spec/standard-events/track.md" >}}) call lets you record the customer events along with any properties associated with them.

A sample `track` call is shown below:

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

All the events tracked by RudderStack are divided into three major Branch event categories:

- [Commerce events](https://help.branch.io/developers-hub/docs/tracking-commerce-content-lifecycle-and-custom-events#track-commerce-events)
- [Content events](https://help.branch.io/developers-hub/docs/tracking-commerce-content-lifecycle-and-custom-events#track-content-events)
- [Lifecycle events](https://help.branch.io/developers-hub/docs/tracking-commerce-content-lifecycle-and-custom-events#track-lifecycle-events)

### Ecommerce event mapping

{{< warning >}}
This destination does not strictly adhere to the [RudderStack Ecommerce Event Spec]({{< ref "event-spec/ecommerce-events-spec/" >}}).
{{< /warning >}}

The following table lists the mapping between the [RudderStack ecommerce events]({{< ref "event-spec/ecommerce-events-spec/_index.md" >}}) and the Branch [commerce events](https://help.branch.io/developers-hub/docs/tracking-commerce-content-lifecycle-and-custom-events#available-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`           |

{{< info >}}
RudderStack also maps the `Spend Credits` event to Branch's `SPEND_CREDITS`, although it is not directly a part of the ecommerce events. 

However, note that the Android device mode integration **does not** support this mapping.
{{< /info >}}

### Content event mapping

The following table lists the mapping between the RudderStack events and the Branch 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` |

{{< info >}}
The above mentioned events are a part of the RudderStack ecommerce events but are mapped to Branch's Content events.
{{< /info >}}

### Lifecycle event mapping

RudderStack supports mapping the following Branch 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`             |

## Reset

The `reset` method resets the previously identified user and related information.

A sample `reset` call is shown:

```objectivec
[[RSClient getInstance] reset];
```

## Property mappings

The following table lists the mapping of the accepted RudderStack properties common to all events:

| RudderStack property | Branch property     |
| :----------------------- | :---------------------- |
| `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`            |

## FAQ

#### Where can I find the Branch key?

To retrieve your Branch key, follow these steps:

1. Log into your [Branch dashboard](https://dashboard.branch.io).
2. Go to **Account Settings** > **Profile**.
3. You can find the Branch Key under **Branch Key and Secret** section:

{{< image src="images/event-stream-destinations/branchio-key.webp" alt="Branch key" >}}