DOCSEARCHbyAlgolia
Submit Docs

Branch React Native SDK

repository·master·Indexed 19 days ago

https://github.com/branchmetrics/react-native-branch-deep-linking-attribution

The Branch React Native SDK provides deep linking, attribution, and deferred deep linking capabilities for React Native applications. It allows developers to track user journeys and drive engagement through intelligent links. The SDK supports environment switching between live and test keys via native Android and iOS configurations, and offers a branch.json configuration file for managing native SDK parameters.

Tokens
11.4K
Snippets
34
Records
47
Agent score
68%

What's inside react-native-branch

  1. Getting started with the Branch React Native SDK

    master

    The Branch React Native SDK enables deep linking and attribution for React Native applications. To integrate Branch, you must follow a multi-step process:

    1. Configure Branch Dashboard: Set up your application in the Branch dashboard.
    2. Install Branch: Add the react-native-branch package to your project.
    3. Configure App: Update your native Android and iOS configurations (e.g., AndroidManifest.xml, Info.plist, and AppDelegate).
    4. Initialize Branch: Initialize the SDK within your application code to start receiving attribution data.
    5. Implement Features: Use the SDK APIs to implement advanced features like deep linking, deferred deep linking, and data sharing.

    For full technical details and API references, refer to the official SDK documentation.

  2. Use branch.json for Branch configuration

    master

    Starting in release 2.0.0-beta.7, you can use a branch.json configuration file in your React Native project to set certain Branch options. This is particularly useful for configuring native SDK parameters that must be set before the native SDK initializes.

    Note that this feature is evolving and support for additional parameters and custom product flavors (Android) or build schemes (iOS) is being added.

    {
  "debugMode": true,
  "liveKey": "key_live_xxxx",
  "testKey": "key_test_yyyy",
  "useTestInstance": true,
  "enableFacebookLinkCheck": true
}

  3. Configure Branch per build type and platform

    master

    You can provide different configurations for debug/release and Android/iOS by using specific filenames. The SDK selects the most specific file available based on the following precedence order:

    Android Debug

    1. branch.android.debug.json
    2. branch.debug.json
    3. branch.android.json
    4. branch.json Note: If app/src/debug/assets/branch.json exists, it will be used for debug builds instead of app/src/main/assets/branch.json.

    Android Release

    1. branch.android.json
    2. branch.json

    iOS Debug

    1. branch.ios.debug.json
    2. branch.debug.json
    3. branch.ios.json
    4. branch.json Note: If branch.debug.json is present in the Copy Bundle Resources, it will be used in debug builds instead of branch.json.

    iOS Release

    1. branch.ios.json
    2. branch.json

  4. Automate conversion using react_native_util

    master

    You can use the react_native_util CLI to automate the process of converting your app to use the React pod from node_modules. This command performs all necessary steps, including adding the 'Start Packager' build phase.

    1. Install the utility via Homebrew: brew install jdee/tap/react_native_util
    2. Navigate to your app directory.
    3. Run the command: rn react_pod
    brew install jdee/tap/react_native_util
cd /path/to/app
rn react_pod

  5. Prerequisites for configuring Branch environments

    master

    Before configuring different Branch environments (Live vs. Test), ensure you have completed the following:

    1. Obtain Keys: Retrieve your Branch live and test keys from the Branch Dashboard. You can switch between 'Live' and 'Test' in the upper left of the dashboard to find the respective keys.
    2. Basic Integration: Ensure the react-native-branch SDK is already integrated into your React Native project.

    Note: Environment switching must be configured in the native Android and iOS projects. There is no support for this configuration via JavaScript.

  6. Install react-native-branch using the React pod (Recommended)

    master

    The preferred installation method is using the React pod (distributed with React Native under node_modules/react-native). This method preserves compatibility with react-native link and simplifies updates to react-native-branch.

    Note: The React pod (as of 0.59.8) will not compile for tvOS. If your app supports tvOS, you must use the 'Installation without the React pod' method instead.

    Steps to install:

    1. Add the package and link it:
      yarn add react-native-branch
react-native link react-native-branch
    2. Install the pods:
      pod install
    3. Follow the remaining setup instructions.
    yarn add react-native-branch
react-native link react-native-branch

# Then run
pod install

  7. Configure iOS to use the Branch Test environment

    master

    To use the Branch Test environment on iOS, you must create a custom build configuration and scheme that uses a preprocessor macro. This allows you to conditionally call useTestInstance in your native code. This method is recommended if you are using Pods to integrate react-native-branch and Branch-SDK.

    ### Step 1: Add a new build configuration
1. In Xcode, go to the **Info** tab of Project settings.
2. Under **Configurations**, click the **+** button.
3. Select `Duplicate "Debug" Configuration`.
4. Name the new configuration `Test-Debug`.

### Step 2: Add a new build scheme
1. Select **Product > Scheme > New Scheme...**.
2. Name it `[YourAppName]-Test` (e.g., `MyApp-Test`).

### Step 3: Configure the new scheme
1. Select **Product > Scheme > Edit Scheme...**.
2. Check the **Shared** box.
3. For **Run**, **Test**, and **Analyze** tasks in the sidebar, change the configuration from `Debug` to `Test-Debug`.

### Step 4: Add a custom preprocessor macro
1. Go to the **Build Settings** tab.
2. Find **Apple LLVM - Preprocessing > Preprocessor Macros**.
3. Double-click the value for `Test-Debug` and add `USE_BRANCH_TEST_INSTANCE=1`.
4. (Optional) If using Swift, add `USE_BRANCH_TEST_INSTANCE` to **Swift-Compiler - Custom Flags > Active Compilation Conditions** for the `Test-Debug` configuration.

### Step 5: Conditional compilation in code
In your `AppDelegate`, call `useTestInstance` before initializing the session:

**Objective-C:**
```objectivec
#ifdef USE_BRANCH_TEST_INSTANCE
    [RNBranch useTestInstance];
#endif

    [RNBranch initSessionWithLaunchOptions:launchOptions isReferrable:YES];

    Swift:

    #if USE_BRANCH_TEST_INSTANCE
    RNBranch.useTestInstance()
#endif

    RNBranch.initSession(launchOptions: launchOptions, isReferrable: true)

    Step 7: Update Podfile

    Map your new configurations in your Podfile so pods are built correctly:

    # Add this line to your Podfile
project "ExampleProject", "Test-Debug" => :debug, "Test-Release" => :release

    Then run pod install.

  9. Install react-native-branch in a new RN 0.60+ project

    master

    For new projects using React Native 0.60 or higher, follow these steps to install the SDK:

    1. Install the package:

      yarn add react-native-branch

    2. Install iOS dependencies:

      cd ios
pod install

    3. Manual branch.json setup: The automatic branch.json creation via react-native link is removed. If your project requires branch.json, you must add it manually (refer to the manual integration guide).

    4. Complete Setup: Follow the standard Branch setup instructions in the main README.md.

    5. Run the app:

      react-native run-ios
# or
react-native run-android

    Note: Do not run react-native link for this SDK.

    yarn add react-native-branch
cd ios
pod install

  10. Install pods and manage workspace

    master

    After configuring your Podfile, follow these steps to complete the installation:

    1. Link dependencies: Run react-native link for each dependency with native components (e.g., react-native link react-native-branch).
    2. Install Pods: From the ios directory, run: pod install --repo-update (The --repo-update flag ensures your local podspec repo is current).
    3. Open the Workspace: From now on, open your .xcworkspace file in Xcode instead of your .xcodeproj file.
    4. Cleanup: Remove the Libraries group from your Xcode project to avoid conflicts. Right-click the group, select Delete, and choose Remove References (do NOT select 'Move to Trash').
    # From the ios directory
pod install --repo-update

  11. Configure Gradle dependencies for Android

    master

    If you used react-native link, no changes to app/build.gradle are required.

    If you are manually importing the project in a native app, add the following to your app/build.gradle:

    implementation project(':react-native-branch')

    Note: Older Gradle versions may require compile instead of implementation.

    Important: If you already use the native Branch SDK, remove any reference to io.branch.sdk.android:library from your dependencies to prevent conflicts, as it is now imported via react-native-branch from Maven.

    Additionally, add the project to your settings.gradle:

    include ':react-native-branch'
project(':react-native-branch').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-branch/android')

    Note: The path to node_modules may vary depending on your project structure.

    // app/build.gradle
implementation project(':react-native-branch')

// settings.gradle
include ':react-native-branch'
project(':react-native-branch').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-branch/android')

  12. Manual conversion: Configure the Podfile

    master

    To manually convert your app to use the React pod from node_modules, follow these steps:

    1. Unlink existing dependencies: Run react-native unlink for each dependency that has native components (e.g., react-native unlink react-native-webview).
    2. Create a Podfile: Create a Podfile in your ios subdirectory. Replace MyApp with your actual application target name.

    Note on subspecs: Your subspecs list may vary based on your specific requirements.

    Note on use_frameworks!: If you add use_frameworks! to your Podfile, CocoaPods will build dependencies as frameworks instead of static libraries. This is recommended but may require changing native imports. For react-native-branch, the import changes as follows:

    • With frameworks: @import react_native_branch;
    • Without frameworks: #import <react-native-branch/RNBranch.h>
    platform :ios, '9.0'

target 'MyApp' do
  pod 'React',
    path: '../node_modules/react-native',
    subspecs: %w[
      Core
      CxxBridge
      DevSupport
      RCTActionSheet
      RCTAnimation
      RCTBlob
      RCTGeolocation
      RCTImage
      RCTLinkingIOS
      RCTNetwork
      RCTSettings
      RCTText
      RCTVibration
      RCTWebSocket
    ]
  pod 'yoga', path: '../node_modules/react-native/ReactCommon/yoga'
  pod 'Folly', podspec: '../node_modules/react-native/third-party-podspecs/Folly.podspec'
end

target 'MyAppTests' do
  pod 'React', path: '../node_modules/react-native', subspecs: %w[Core CxxBridge]
  pod 'yoga', path: '../node_modules/react-native/ReactCommon/yoga'
  pod 'Folly', podspec: '../node_modules/react-native/third-party-podspecs/Folly.podspec'
end