> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# React Native SDK Expo Integration

> Integrate Branch into your Expo app with this guide, covering setup, deep linking, paid ads, and troubleshooting.

> **Plugin not maintained by Branch**
>
> We maintain the Branch React Native SDK, but we don't maintain the `@config-plugins/react-native-branch` plugin. It's a community-maintained package in Expo's [config-plugins repository](https://github.com/expo/config-plugins/tree/main/packages/react-native-branch), so please report plugin issues on its separate [issue tracker](https://github.com/expo/config-plugins/issues).

## Overview

This guide outlines how to integrate the [Branch React Native SDK](https://www.npmjs.com/package/react-native-branch) into an Expo-based app using the `@config-plugins/react-native-branch` [plugin](https://www.npmjs.com/package/@config-plugins/react-native-branch).

This guide covers an Expo-managed workflow. If you need full native control, see the [React Native SDK Basic Integration](https://help.branch.io/developer-hub/react-native-basic-integration.md) guide.

## Before you begin

Before you begin this integration, make sure you:

- Have an Expo-managed or prebuild workflow using Expo SDK 54 or higher (run `npx expo install expo` to install or update)
- Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/). Expo Go doesn't support the plugin because it adds native code.
- Understand which Branch products you are implementing:

  - Attribution and deep linking
  - Paid ads
  - Other advanced features

You will also need:

- Your Branch Key (Live or Test)

  - [Branch Keys in legacy Branch](https://help.branch.io/account-hub/profile-settings.md)
  - [Branch Keys in new Branch](https://help.branch.io/account-hub/credentials-new.md)
- Your Branch link domains
- Confirmation whether SKAdNetwork support is required for your configuration

## Set up Branch in your Expo app

### 1. Configure Branch

Configure Branch for your application:

- [iOS Branch configuration steps](https://help.branch.io/developer-hub/ios-basic-integration.md#_1-configure-branch)
- [Android Branch configuration steps](https://help.branch.io/developer-hub/android-basic-integration.md#_1-configure-branch)

Make sure to configure your default link settings as part of the setup process.

### 2. Install Branch

Install the [Branch React Native SDK](https://www.npmjs.com/package/react-native-branch). Use the version listed for your Expo SDK in the plugin's [version table](https://github.com/expo/config-plugins/tree/main/packages/react-native-branch#versioning).

```
npx expo install react-native-branch@<version>
```

### 3. Add plugin

Add the [plugin](https://www.npmjs.com/package/@config-plugins/react-native-branch), using the version listed for your Expo SDK in the same table.

```
npx expo install @config-plugins/react-native-branch@<version>
```

### 4. Configure plugin

Set environment variables using [EAS](https://docs.expo.dev/eas/environment-variables/).

If you don’t have an `app.config.js` or `app.config.ts` in your project, start by manually creating one. Then, add the following code:

```typescript
export default {
  plugins: [
    [
      '@config-plugins/react-native-branch',
      {
        apiKey: process.env.BRANCH_API_KEY, // Required
        iosUniversalLinkDomains: [
          process.env.BRANCH_DOMAIN_LINK,
          process.env.BRANCH_DOMAIN_LINK_ALT,
        ],
      },
    ],
  ],
  ios: {
    associatedDomains: [
      `applinks:${process.env.BRANCH_DOMAIN_LINK}`,
      `applinks:${process.env.BRANCH_DOMAIN_LINK_ALT}`,
    ],
  },
  android: {
    intentFilters: [
      {
        action: "VIEW",
        autoVerify: true,
        category: ["BROWSABLE", "DEFAULT"],
        data: [
          { scheme: 'https', host: `${process.env.BRANCH_DOMAIN_LINK}` },
          { scheme: 'https', host: `${process.env.BRANCH_DOMAIN_LINK_ALT}` },
        ],
      },
    ],
  },
}
```

If your build is failing in local development after configuring the plugin, see the [Troubleshooting](https://help.branch.io/developer-hub/react-native-expo-integration.md#build-fails-without-branch-api-key-in-local-development) section.

#### iosUniversalLinkDomains

The `iosUniversalLinkDomains` option tells the Branch iOS SDK which domains your Branch Links use. Include both your primary and alternate (`-alternate`) link domains if your app uses both.

This is separate from `ios.associatedDomains`, which registers your domains with iOS. Without it, Universal Links don't open your app.

### 5. Subscribe to deep link data

The plugin handles native Branch initialization automatically. For details on native Branch initialization, see the [React Native SDK Basic Integration](https://help.branch.io/developer-hub/react-native-basic-integration.md) guide.

To listen for deep link data, subscribe in your app's entry point:

```typescript
import branch from 'react-native-branch'

branch.subscribe(({ error, params }) => {
  if (error) {
    console.error('Branch error:', error)
    return
  }

  console.log('Branch params:', params)
})
```

### 6. Configure permissions on Android and iOS

#### Android

Add the Google Advertising ID (GAID) and Google Play Install Referrer permissions so Branch can accurately match clicks to installs and downstream events. In the `app.json` file, add the following:

```json
{
  "expo": {
    "android": {
      "permissions": [
        "com.google.android.gms.permission.AD_ID",
        "com.android.vending.INSTALL_REFERRER"
      ]
    }
  }
}
```

#### iOS

To use Branch's NativeLink™ feature, add the following entry to your `Branch.json` file to allow the SDK to check the pasteboard for the Branch Link:

```json
{
  "checkPasteboardOnInstall": true
}
```

### 7. (Optional) Set up paid ads

If you're using Branch for paid ad attribution, additional setup is required.

See the following guides to set up and test your paid ads implementation:

- [Enable SKAdNetwork](https://help.branch.io/marketer-hub/enable-skadnetwork.md)
- [Test Ads Campaign Setup](https://help.branch.io/marketer-hub/testing-ads-campaign-setup.md)

### 8. Validate integration

Before testing on device, use the [Link Validator](https://help.branch.io/marketer-hub/link-validator.md) in Branch to confirm your links are configured correctly and preview the expected user flow across different platforms and click sources.

Then validate your integration using the three scenarios below. In each case, your `subscribe` callback should receive and log the link data.

1. **Test Universal Link opening:** Open a Branch Link from Safari (iOS) and Chrome (Android). The app should open directly without extra dialogs or browser redirects.
2. **Test cold-start deep link behavior:** Force quit the app, then open a Branch Link. The app should launch and take you to your content.
3. **Test background resume behavior:** With the app backgrounded, tap a Branch Link. The app should resume and take you to your content.

For additional validation and testing, use the following guides:

**iOS**

- [iOS Validation](https://help.branch.io/developer-hub/ios-basic-integration.md#_8-validate-integration)
- [iOS SDK Testing](https://help.branch.io/developer-hub/ios-testing.md)

**Android**

- [Android Validation](https://help.branch.io/developer-hub/android-basic-integration.md#_8-validate-integration)
- [Android SDK Testing](https://help.branch.io/developer-hub/android-testing.md)

## Next steps

Once you’ve integrated Branch into your Expo app, you can use any of the features documented in the [React Native SDK Full Reference](https://help.branch.io/developer-hub/react-native-full-reference.md) guide, including creating Branch Links, tracking Branch Events, and handling Branch Universal Objects.

## Troubleshooting

For general iOS and Android troubleshooting suggestions, use the following guides:

- [iOS SDK Troubleshooting](https://help.branch.io/developer-hub/ios-troubleshooting.md)
- [Android SDK Troubleshooting](https://help.branch.io/developer-hub/android-troubleshooting.md)

#### Plugin version errors

Version errors mean your Expo SDK, the Branch React Native SDK, and the plugin don't match. Install the versions listed for your Expo SDK in the plugin's [version table](https://github.com/expo/config-plugins/tree/main/packages/react-native-branch#versioning). Avoid `--legacy-peer-deps`. It skips the version check and can leave you with versions that don't work together.

#### Build fails without BRANCH_API_KEY in local development

If `BRANCH_API_KEY` is not set in your environment, the plugin will fail the build, even if you're not testing Branch functionality. To avoid this, conditionally load the plugin only for production builds:

```
export default {
  plugins: IS_DEV
    ? [...plugins, ...devPlugins]
    : [...plugins, ...prodPlugins],
}
```

Place the `@config-plugins/react-native-branch` plugin inside `prodPlugins`.

#### Prebuild fails

If prebuild fails after adding the `@config-plugins/react-native-branch` plugin, try running a clean prebuild:

```
npx expo prebuild --clean
```

#### Unable to use both Test and Live Branch Keys

On Expo SDK 55 or later, you can add `testApiKey` alongside `apiKey` in the plugin configuration. Then set `enableTestEnvironment` to `true` in any build that should use the test key. This works on both iOS and Android. To open test links in that build, also add your test link domain to the associated domains and intent filters in [step 4](https://help.branch.io/developer-hub/react-native-expo-integration.md#_4-configure-plugin).

On Expo SDK 54, use one of these workarounds:

- Use separate builds for Test and Live
- Use only your Branch Live Key across all your environments
- Implement custom build-time logic

#### Deep links do not open in the app

If your deep links are not properly opening your app:

- Verify [associatedDomains (iOS)](https://help.branch.io/developer-hub/react-native-expo-integration.md#_4-configure-plugin)
- Verify [intentFilters (Android)](https://help.branch.io/developer-hub/react-native-expo-integration.md#_4-configure-plugin)
- Confirm [domain configuration](https://help.branch.io/account-hub/basic-link-configuration.md#_5-link-domain) in Branch
- Confirm [AASA file](https://help.branch.io/developer-hub/ios-testing.md) is accessible

#### SKAdNetwork attribution is unclear

If your SKAdNetwork attribution data is not showing up or doesn’t look correct in Branch:

- Confirm SKAdNetwork IDs are registered

- Validate Branch reporting
- Test install flow from paid campaign

For SKAdNetwork setup and validation, see our [Enable SKAdNetwork](https://help.branch.io/marketer-hub/enable-skadnetwork.md) guide.

#### Branch analytics fields are empty after removing Firebase

If you migrated away from the Firebase SDK and Branch analytics fields like `$~campaign` are unpopulated, you may need to explicitly install `expo-tracking-transparency`. On Android, this library was previously bundled with Firebase in Expo environments.

`npx expo install expo-tracking-transparency`

Also confirm that your Proguard `-keep` rules are correctly configured for the Branch React Native SDK.