{"id":11761,"library":"react-native-branch","title":"Branch Metrics React Native SDK","description":"react-native-branch is the official React Native SDK for Branch Metrics, a comprehensive mobile linking and attribution platform. It enables developers to integrate deep linking, deferred deep linking, mobile attribution, and analytics into their React Native applications, supporting both iOS and Android platforms. The current stable version is 6.9.0, with frequent updates (typically monthly or bi-monthly) to align with native Branch SDK releases and to expose new methods for compliance and functionality. Key differentiators include its robust deep linking capabilities across platforms, detailed attribution analytics for marketing campaigns, and features like Universal Links and App Links for seamless user experiences. It abstracts much of the underlying native SDK complexity, providing a unified JavaScript interface.","status":"active","version":"6.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/BranchMetrics/react-native-branch-deep-linking-attribution","tags":["javascript","react-native","react-component","ios","android","branch","metrics","deeplink","deep","typescript"],"install":[{"cmd":"npm install react-native-branch","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-branch","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-branch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native application integration.","package":"react-native","optional":false}],"imports":[{"note":"The primary SDK instance is typically imported as a default export, though named exports for types and specific classes also exist. ES Module syntax is preferred.","wrong":"const branch = require('react-native-branch');","symbol":"branch","correct":"import branch from 'react-native-branch';"},{"note":"Used to represent content for deep linking and events. It's a named export, not a default.","wrong":"import BranchUniversalObject from 'react-native-branch';","symbol":"BranchUniversalObject","correct":"import { BranchUniversalObject } from 'react-native-branch';"},{"note":"Used for tracking custom events within Branch Analytics. It's a named export.","wrong":"import BranchEvent from 'react-native-branch';","symbol":"BranchEvent","correct":"import { BranchEvent } from 'react-native-branch';"}],"quickstart":{"code":"import React, { useEffect, useState } from 'react';\nimport { Text, View, StyleSheet, Alert, Linking } from 'react-native';\nimport branch, { BranchUniversalObject, BranchEvent } from 'react-native-branch';\n\nconst HomeScreen = () => {\n  const [latestParams, setLatestParams] = useState(null);\n\n  useEffect(() => {\n    // Branch initialization and deep link subscription\n    const unsubscribe = branch.subscribe(({ error, params, uri }) => {\n      if (error) {\n        console.error('Error from Branch: ' + error);\n        return;\n      }\n      console.log('Branch Params:', params);\n      console.log('Branch URI:', uri);\n      setLatestParams(params);\n\n      if (params['+non_branch_link']) {\n        const nonBranchUrl = params['+non_branch_link'];\n        Alert.alert('Non-Branch Link', `Opened non-Branch URL: ${nonBranchUrl}`);\n        Linking.openURL(nonBranchUrl);\n        return;\n      }\n\n      if (params['+clicked_branch_link']) {\n        Alert.alert('Branch Link Opened', `Data: ${JSON.stringify(params, null, 2)}`);\n        // Handle routing based on params (e.g., params.screen, params.productId)\n      } else {\n        Alert.alert('App Opened', 'No Branch link clicked or initial session.');\n      }\n    });\n\n    // Example: Create a Branch Universal Object and generate a short URL\n    const createAndShareLink = async () => {\n      try {\n        let buo = await branch.createBranchUniversalObject('content/12345', {\n          locallyIndex: true,\n          title: 'My Awesome Product',\n          contentDescription: 'Check out this amazing product!',\n          contentMetadata: {\n            productId: '12345',\n            itemCategory: 'electronics',\n            customData: 'important_info',\n          },\n        });\n\n        let linkProperties = {\n          feature: 'share',\n          channel: 'app_share',\n          campaign: 'product_promo',\n        };\n\n        let controlParams = {\n          $desktop_url: 'https://example.com/product/12345',\n          $ios_url: 'https://apps.apple.com/app/id123456789',\n          $android_url: 'https://play.google.com/store/apps/details?id=com.yourapp',\n        };\n\n        let { url } = await buo.generateShortUrl(linkProperties, controlParams);\n        console.log('Generated Branch URL:', url);\n\n        // Example: Log a custom event\n        let event = new BranchEvent(BranchEvent.ViewItem, buo, {\n          transaction_id: 'trans_abc123',\n          currency: 'USD',\n          revenue: 10.00,\n        });\n        event.logEvent();\n        console.log('Logged custom event: ViewItem');\n\n      } catch (err) {\n        console.error('Error creating/logging Branch event or link:', err);\n      }\n    };\n\n    createAndShareLink();\n\n    return () => {\n      unsubscribe();\n    };\n  }, []);\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.title}>Branch SDK Example</Text>\n      {latestParams ? (\n        <View>\n          <Text style={styles.subtitle}>Latest Deep Link Params:</Text>\n          <Text style={styles.params}>{JSON.stringify(latestParams, null, 2)}</Text>\n        </View>\n      ) : (\n        <Text>Waiting for deep link or initial app open...</Text>\n      )}\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20,\n    backgroundColor: '#F5FCFF',\n  },\n  title: {\n    fontSize: 24,\n    fontWeight: 'bold',\n    marginBottom: 20,\n  },\n  subtitle: {\n    fontSize: 18,\n    fontWeight: '600',\n    marginTop: 10,\n    marginBottom: 5,\n  },\n  params: {\n    fontFamily: Platform.OS === 'ios' ? 'Courier' : 'monospace',\n    fontSize: 12,\n    backgroundColor: '#e0e0e0',\n    padding: 10,\n    borderRadius: 5,\n  },\n});\n\nexport default HomeScreen;\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the Branch SDK, subscribe to deep link events, and create/log a Branch Universal Object and custom event."},"warnings":[{"fix":"Review the official Branch React Native SDK documentation for specific version migration steps. Typically involves updating native config files, removing duplicate native SDK installations (e.g., from Podfile if already embedded by NPM), and adjusting import statements in native code.","message":"Major version updates of `react-native-branch` often involve significant updates to the underlying native iOS and Android SDKs. These can introduce breaking changes requiring manual updates to native project files (e.g., `Info.plist`, `AndroidManifest.xml`, `AppDelegate.mm`/`.swift`, `MainApplication.java`/`.kt`, `Podfile`). Always consult the official Branch SDK documentation and migration guides for each major release.","severity":"breaking","affected_versions":">=2.0.0, >=6.0.0"},{"fix":"Ensure `Associated Domains` are correctly configured in Xcode, `Info.plist` has `branch_universal_link_domains` and URL Schemes, and `AndroidManifest.xml` includes `intent-filters` for your Branch domains and `BranchKey`. Also, check if `deferInitForPluginRuntime: true` is set in `branch.json` for cold start deep link reliability, and call `RNBranchModule.initSession` in `MainActivity.java`/`.kt` and `AppDelegate.mm`/`.swift`.","message":"Deep links failing to open the app or navigate correctly, especially from a killed state on iOS or Android, is a very common issue. This often stems from incorrect or incomplete native configuration for Universal Links (iOS) or App Links (Android).","severity":"gotcha","affected_versions":">=0.60"},{"fix":"Remove any calls to `branch.setDebug()`. Refer to the latest Branch SDK documentation for current debugging practices, which often involve setting log levels or flags in `branch.json` or native configuration.","message":"The `setDebug()` method was removed in version 6.1.0. Debugging is now handled differently.","severity":"breaking","affected_versions":">=6.1.0"},{"fix":"For Expo managed apps, consider using `@config-plugins/react-native-branch` which attempts to inject necessary configurations. However, for full control and all Branch features, converting to an Expo Bare Workflow or using a custom development client might be necessary. Alternatively, evaluate if simpler deep linking solutions like `expo-linking` suffice.","message":"Expo managed workflow projects have limitations with `react-native-branch` due to the need for custom native module configuration and early lifecycle method access. Direct integration is often problematic.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure that native Branch SDKs are *not* manually added via `build.gradle` or `Podfile` if using `react-native-branch` v2.0.0 or later. The NPM module embeds the native SDKs. Remove `pod 'Branch-SDK'` from your Podfile if it's there.","message":"Older versions (prior to v2.0.0) of `react-native-branch` might have required manual addition of native Branch SDKs via Gradle or CocoaPods. This is no longer necessary and can cause build conflicts.","severity":"deprecated","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your `linking` configuration in `React Navigation` (e.g., in your root navigator) accurately defines the paths and screens that correspond to the data you expect from Branch deep links. Use `branch.subscribe` to get params and debug the expected navigation structure.","cause":"This error typically occurs when React Navigation's deep linking configuration doesn't correctly map the incoming Branch deep link parameters (e.g., `screen` or `path`) to an existing route in your app's navigation stack.","error":"Error: The navigation state parsed from the URL contains routes not present in the root navigator. This usually means that the linking configuration doesn't match the navigation structure."},{"fix":"If using `react-native-branch` version 2.0.0 or newer, remove any manual `pod 'Branch-SDK'` or `pod 'Branch'` entries from your `Podfile`. The React Native module handles native SDK inclusion automatically. Run `pod install --repo-update` after modifying your Podfile.","cause":"Often indicates that the native Branch SDK is included multiple times in your iOS project, for example, once by `react-native-branch` and again manually via CocoaPods or direct framework embedding.","error":"ld: 1 duplicate symbol for architecture arm64"},{"fix":"Increase your project's `minSdkVersion` in `android/app/build.gradle` to match or exceed the requirement of `react-native-branch`. For modern React Native apps, a `minSdkVersion` of 21 or higher is generally recommended. Update to `minSdkVersion = 21` (or higher) in `defaultConfig` block.","cause":"Your app's `minSdkVersion` in `android/app/build.gradle` is lower than the minimum required by `react-native-branch` (or its embedded native Android SDK).","error":"Manifest merger failed : uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:react-native-branch] AndroidManifest.xml"},{"fix":"Try importing `branch` as a named export: `import { branch } from 'react-native-branch';`. If that doesn't work, refer to the specific version's documentation or use `import * as branch from 'react-native-branch';` for older CJS-like modules. The current official documentation implies `import branch from 'react-native-branch'` is correct.","cause":"You are attempting to import `branch` as a default export, but the module might be configured to use named exports for the primary object, or you are using an older version where the import pattern was different.","error":"Type 'typeof import(\"/path/to/node_modules/react-native-branch/index\")' has no default export."}],"ecosystem":"npm"}