Branch React Native SDK: deep linking and attribution for mobile apps

A thin bridge over two native libraries

The repository is the React Native SDK from Branch Metrics, and its shape is that of a bridge rather than a service. The `main` entry point is `src/index.js` with TypeScript declarations at `src/index.d.ts`, and the package publishes the `android` and `ios` directories alongside the podspec, so what npm delivers is the JavaScript layer plus the two native subprojects that the React Native autolinking mechanism picks up. The described purpose is deep linking and attribution, with deep links described as powering paid acquisition and re-engagement campaigns, referral programs, content sharing, deep linked emails, smart banners and custom user onboarding. The audience is a mobile developer who has chosen Branch as the provider of those capabilities and needs the React Native bindings rather than a native integration done by hand in Swift and Kotlin.

The README is a table of contents for someone else's documentation

The README is short and it is entirely links. It opens by pointing at the SDK documentation at help.branch.io for full details, and then lists the integration steps as named anchors: Configure Branch, Install Branch, Configure App, Initialize Branch, Implement Features and Troubleshoot Issues. Each of those is a link into the Branch developer hub, with the configuration step pointing at the Branch dashboard, the install step at the Branch installation guide, the app step at the app configuration guide and the validation step at the troubleshooting section. The README also says to contact the Support team for feedback or assistance with integration or troubleshooting. So the repository does not contain installation steps of its own, and that is a deliberate arrangement: the docs live with the platform so that a change to the Branch service or the dashboard can be reflected without a release of the SDK.

The package manifest tells you what you are actually installing

The packaging metadata is where the concrete facts live. The package is `react-native-branch` at version 7.0.0, published from `src/index.js` with types alongside:

  "name": "react-native-branch",
  "version": "7.0.0",
  "description": "Branch Metrics React Native SDK",
  "main": "src/index.js",
  "types": "src/index.d.ts",

The `files` array is what actually ships, and it is short:

  "files": [
    "android",
    "branch.example.json",
    "ios",
    "react-native-branch.podspec",
    "src"
  ],
  "scripts": {
    "lint": "eslint src test",
    "test": "jest --coverage"
  },

Two things are worth noticing there. The array also carries an exclusion entry that keeps development podspecs out of the published tarball, so the podspec you resolve is the release one, and the `branch.example.json` file is included deliberately, because it is the sample configuration an integrator copies rather than something the runtime loads. The `scripts` block shows how the project itself is worked on, with `lint` running ESLint over `src` and `test` and `test` running Jest with coverage, which tells you the JavaScript layer is unit tested against a mocked native side rather than exercised on a device for every change.

The peer dependency is the first thing to check on an existing app

The manifest declares a single peer dependency:

  "peerDependencies": {
    "react-native": ">= 0.73.0"
  },

That constraint, React Native 0.73.0 or newer, is the first thing to verify against an existing codebase, because a peer dependency is not installed for you and a mismatch shows up as a broken build rather than a clean error. The development versions give a sense of what the project is tested against: React 19.2.3 and React Native 0.83.2 in the dev dependencies, alongside Babel 7, Jest 29 and the React Native community ESLint configuration. The gap between a peer floor of 0.73 and a tested version of 0.83 is worth keeping in mind, since it tells you the SDK is expected to work across a wide range of React Native versions while the continuous integration only exercises the newest one.

Three test harnesses in the tree hint at how much is native

The repository layout shows several separate testing environments. There is a `test/` directory with the Jest unit tests, `native-tests/` for tests that exercise the native layer, `ReactNativeInteropTest/` for interoperability, and two application fixtures, `branchreactnativetestbed/` and `branch-sdk-automation-testbed/`. Alongside them sit `android/` and `ios/` for the two platform implementations, `src/` for the JavaScript bridge, `docs/`, a `runAllTests` script at the root, and `react-native-branch.podspec` for the CocoaPods integration. The presence of three distinct harnesses is a fair signal about the shape of the work. A JavaScript wrapper over two native libraries cannot be tested by Jest alone, because most of the interesting behaviour lives in the native code and in the platform-specific deep link handling, so the repository carries a native test path and an application-level fixture as well.

Configuration lives in a JSON file that ships with the package

The `branch.example.json` file at the root is the sample configuration, and it is listed in the `files` array so it is available to anyone who installs the package. This is the concrete artefact an integrator copies, fills in with their own Branch keys, and points the native projects at. The `branch.example.json` name is deliberate. An example file with example values can be copied and edited without anyone editing a working configuration that other people also have, and it means the SDK ships with a known-good shape rather than leaving the format to be guessed. The iOS side of that configuration is normally what the podspec references, and the Android side has its own equivalent in the `android/` directory, which is why both platform directories are published in the tarball rather than being pulled from a separate repository at build time.

Where the Branch React Native SDK is the wrong tool

Three limits are worth stating plainly. The first is that this is a client for a hosted platform. Deep linking here is not a local resolution scheme; it depends on Branch's dashboard, its link routing, its link configuration and its identity resolution to match an incoming link to a device and a user. An application that needs deep linking to work with no third-party service in the path, or that needs to own its link graph and its user identity mapping, needs a different approach entirely, and swapping later means removing the SDK, rewriting the link handling and dealing with the historical links already in the wild. The second is that the documentation is not versioned with the code. The README points at help.branch.io, so the steps you follow are whatever is current on the site, and a specific release of the SDK may not match the current documentation. The third is that this is one provider's SDK, so the abstraction cost of using it is paid in the places where the Branch-specific model, with its campaign parameters and its attribution windows, leaks into your own code.

The alternative is a self-hosted or app-associating linker

The realistic alternative is to build the linking on the platform's own primitives. On iOS that means Universal Links, and on Android it means App Links, both of which are associations between your domain and your app that the operating system resolves without any third-party service. The difference in approach is where the link data goes. With Universal Links and App Links, the link is a URL pointing at your own domain, your own server resolves the path to a destination, and the association is verified by a file you host on your domain, so attribution data comes from your own analytics rather than from the provider's dashboard. What you give up is everything Branch packages: campaign tracking across the acquisition funnel, deferred deep linking that routes a user to the right place even before they install, cross-platform identity stitching, referral programmes, and the dashboard to look at it. The trade is ownership against capability. If the link is only a way into a piece of content in your own app, platform-native linking is enough and simpler. If the link is the mechanism by which you buy users, measure them and bring them back, the hosted provider is doing work that is genuinely hard to rebuild.

Editorial conclusion

react-native-branch fits a mobile team that has already decided to use Branch as its attribution and deep linking provider and needs the React Native bridge for it, and it is a reasonable choice if you are starting a new app rather than migrating an existing one. It is the wrong choice if you are looking for a self-hosted or open source linking service, since the SDK is a client for a hosted platform and carries a service dependency that a library cannot remove. Before you adopt it, read the integration steps on help.branch.io, since the repository README only links to them, and check that your React Native version satisfies the `>= 0.73.0` peer dependency.

Frequently asked questions

Official sources

1. BranchMetrics/react-native-branch-deep-linking-attribution on GitHub
2. License: MIT
3. Project website
4. README
5. Releases