ReferralHero Integration Guide for React Native Apps

This guide will help you integrate ReferralHero system into your React Native mobile app. With this setup, users clicking on ReferralHero links will be redirected seamlessly to your app — whether it’s already installed or not — and referral data will be tracked automatically.

📌 Step 1: Configuration in ReferralHero Campaign

1. Enable Mobile Apps

   • In the campaign builder under "Goals", enable "Track iPhone & Android app downloads".

   • Enter your App Store and Play Store URLs.

2. Enable Branch.io Credentials (if you already have Branch.io account) else If you don't have Branch.io credentials, no worries — we'll set everything up for you.

   • Toggle on "Do you have Branch.io?"

   • Provide your Branch.io Secret Key and App ID in the respective fields.

---

⚙️ Step 2: Setup Redirection in Branch.io Dashboard (If you have Branch.io Account)

1. Go to your Branch.io dashboard → App Settings.

2. Configure the redirects for both Android and iOS platforms:

   • Add your app’s custom URI scheme (if applicable).

   • Provide App Store URLs and Bundle ID.

   • Specify the redirection behaviour when the app is installed or not installed.

---

📱 React Native App Integration with Branch.io

Install Dependency

npm install react-native-branch

---

🧩 iOS Setup

1. Bundle Identifier

Ensure your Apple Bundle ID in Xcode matches the one configured in the Branch.io dashboard. Find the bundle identifier for the relevant target associated with your project in Xcode, under the "Signing & Capabilities" tab.

2. Associated Domains

• In the Branch Dashboard, find your Link Domains.

• In Xcode → Target → Signing & Capabilities, add associated domains in this format:

  applinks:your-subdomain.app.link

3. Info.plist Configuration

Branch requires specific key/value pairs to be added to your project's Info.plist file:

• branch_universal_link_domains: Specifies the associated domains your app will support for universal links.

• branch_key: Your Branch live key (you can also include a test key for development purposes).

• CFBundleURLTypes: Defines your app’s URL schemes and identifiers, allowing Branch to correctly handle app openings via deep links.

Add the following to your Info.plist:

<key>branch_key</key>
<string>key_test_kyqc*****************</string>

<key>branch_universal_link_domains</key>
<array>
  <string>i2koh.test-app.link</string>
  <string>i2koh-alternate.test-app.link</string>
</array>

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>app_name</string>
    </array>
  </dict>
</array>

4. AppDelegate.swift Setup

In your AppDelegate.swift, add:

import UIKit
import React
import React_RCTAppDelegate
import ReactAppDependencyProvider
import RNBranch

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?
  var reactNativeDelegate: ReactNativeDelegate?
  var reactNativeFactory: RCTReactNativeFactory?

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    RNBranch.useTestInstance() // Optional for test key
    RNBranch.initSession(launchOptions: launchOptions, isReferrable: true)

    let delegate = ReactNativeDelegate()
    let factory = RCTReactNativeFactory(delegate: delegate)
    delegate.dependencyProvider = RCTAppDependencyProvider()

    reactNativeDelegate = delegate
    reactNativeFactory = factory

    window = UIWindow(frame: UIScreen.main.bounds)
    factory.startReactNative(withModuleName: "react_native", in: window, launchOptions: launchOptions)

    return true
  }

  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    RNBranch.application(app, open: url, options: options)
    return true
  }

  func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    RNBranch.continue(userActivity)
    return true
  }
}

---

🤖 Android Setup

1. AndroidManifest.xml

Add the following inside <application> tag:

<meta-data
  android:name="io.branch.sdk.BranchKey"
  android:value="key_test_kyqc*****************" />
<meta-data
  android:name="io.branch.sdk.TestMode"
  android:value="true" />

<activity android:name=".MainActivity" ...>
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="i2koh.test-app.link" />
  </intent-filter>
</activity>

2. MainActivity.kt

import io.branch.rnbranch.*
import android.os.Bundle
import android.content.Intent

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  RNBranchModule.initSession(intent?.data, this)
}

override fun onNewIntent(intent: Intent?) {
  super.onNewIntent(intent)
  setIntent(intent)
  RNBranchModule.reInitSession(this)
}

3. MainApplication.kt

import io.branch.rnbranch.RNBranchModule
import io.branch.rnbranch.RNBranchPackage

override fun onCreate() {
  super.onCreate()
  RNBranchModule.getAutoInstance(this)
}

override fun getPackages(): List<ReactPackage> {
  return listOf(
    ...,
    RNBranchPackage()
  )
}

---

🧪 Reading Link Parameters in App

Add the following in your app’s entry point (e.g., App.js):

import React, { useEffect, useState } from "react";
import AsyncStorage from "@react-native-async-storage/async-storage";
import branch from 'react-native-branch';

function App() {
  const [isLoading, setIsLoading] = useState(true);

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

      if (params['+clicked_branch_link']) {
        const visitorId = params['visitor_id'];
        const referralCode = params['referral_code'];

        if (visitorId) {
          AsyncStorage.setItem("visitor_id", visitorId);
        }
        if (referralCode) {
          AsyncStorage.setItem("referral_code", referralCode);
        }
      }
    });

    checkLoginStatus();
    return () => unsubscribe();
  }, []);

  const checkLoginStatus = async () => {
    try {
      const token = await AsyncStorage.getItem("loggedIn");
      // your login logic
    } catch (error) {
      console.log(error);
    } finally {
      setIsLoading(false);
    }
  };

  if (isLoading) return null;

  return (
    // your navigation container or main view
  );
}

export default App;

✅ You can now use the visitor_id and referral_code from the link when calling ReferralHero APIs during user registration.