# Getting Started

## Overview <a href="#overview" id="overview"></a>

The ReferralHero API is organized around REST. Our API has predictable, resource-oriented URLs.[ JSON](http://www.json.org/) is returned by all API responses, including errors.

## 1. Get Your ReferralHero Keys & Token

1. **API Token:**\
   Retrieve your `API_TOKEN` from the ReferralHero Dashboard by navigating to -> API: [ReferralHero Dashboard](https://app.referralhero.com/dashboard/apis).

<figure><img src="https://support.referralhero.com/~gitbook/image?url=https%3A%2F%2F363135598-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LsuqexOLPOWiUrWg_Ko%252Fuploads%252FDMgQ4IAB7f9c5MKDVirh%252Fimage.png%3Falt%3Dmedia%26token%3Df70e23f6-4716-437d-a2d0-b160b02bfc91&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=d476631&#x26;sv=2" alt=""><figcaption></figcaption></figure>

2. **Branch Key & Domains:**

   If you already have a **Branch** account, keep your credentials ready.

   If not — no worries, we’ll handle the setup for you.

   Once you configure your **referral tracking campaign** and enable **Mobile Apps**, we’ll email you the required credentials for integration:

   * `branch_key`&#x20;
   * `branch_universal_link_domains`

> If you don’t receive the email, please contact ReferralHero Support at <support@referralhero.com>

***

## 2. Install Dependencies

* **Using NPM**

  ```bash
  npm install axios
  npm install react-native-branch
  ```
* **Using yarn**

  ```bash
  yarn add axios
  yarn add react-native-branch
  ```

***

## 3. Configure App

**📱 iOS Configuration**

1. **Associated Domains**

   To configure:

   1. Open your project in **Xcode**.
   2. Navigate to **Target → Signing & Capabilities**.
   3. Add a new **Associated Domains** entry.
   4. For each domain, add an entry in the following format:

      ```
      applinks:your-subdomain-1.app.link
      applinks:your-subdomain-2-alternate.app.link
      ```

      If you've received your `branch_universal_link_domains` from us (as noted in **Step 1**), add **each** domain listed using the `applinks:` prefix.\
      \
      ✅ Example:\
      If `branch_universal_link_domains` =

      ```json
      ["referralhero.app.link", "referralhero-alternate.app.link"]
      ```

      \
      Then in **Associated Domains**, you would add:

      ```
      applinks:referralhero.app.link
      applinks:referralhero-alternate.app.link
      ```

<figure><img src="/files/icepS0uCd6OQiOTwAcxM" alt=""><figcaption></figcaption></figure>

2. **Info.plist Configuration**\
   Referralhero 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 key
* `CFBundleURLTypes`: Defines your app’s URL schemes and identifiers, allowing ReferralHero to correctly handle app openings via universal links.

**Add the following to your `Info.plist`:**

```xml
<key>branch_key</key>
<string>key_live_kyqc*****************</string>

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

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

3. **AppDelegate.swift Setup**\
   add the following to your app's AppDelegate file:

{% tabs %}
{% tab title="Swift" %}

```swift
import RNBranch

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    RNBranch.initSession(launchOptions: launchOptions)

    return true
  }

  func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : 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
  }
}

```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
#import "AppDelegate.h"
#import <RNBranch/RNBranch.h>
  
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Optional: Uncomment next line to use test instead of live key
    // [RNBranch useTestInstance];
    [RNBranch initSessionWithLaunchOptions:launchOptions isReferrable:YES];
    NSURL *jsCodeLocation;
    //...
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  [RNBranch application:app openURL:url options:options];
  return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
  [RNBranch continueUserActivity:userActivity];
  return YES;
}

@end

```

{% endtab %}
{% endtabs %}

***

**🤖 Android Configuration**

1. **AndroidManifest.xml**\
   Add the following inside the `<application>` tag:

   ```xml
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
   <!-- Branch SDK Key -->
   <meta-data android:name="io.branch.sdk.BranchKey" android:value="key_live_XXX" />
   <!-- Custom URI scheme (optional) -->
   <intent-filter>
       <data android:scheme="your.scheme" android:host="open" />
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
   </intent-filter>
   <!-- Branch Universal Link Domains -->
   <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="example.app.link" />
       <data android:scheme="https" android:host="example-alternate.app.link" />
   </intent-filter>
   ```
2. **MainActivity.kt**

   ```kotlin
   import io.branch.rnbranch.*
   import android.content.Intent
   // ...
   override fun onStart() {
       super.onStart()
       RNBranchModule.initSession(getIntent().getData(), this)
   }
   override fun onNewIntent(intent: Intent?) {
       super.onNewIntent(intent)
       setIntent(intent)
       RNBranchModule.reInitSession(this)
   }
   ```
3. **MainApplication.kt**

   ```kotlin
   import io.branch.rnbranch.*
   // ...
   override fun onCreate() {
       super.onCreate()
       RNBranchModule.getAutoInstance(this)
       SoLoader.init(this, false)
       if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
           // If you opted-in for the New Architecture, we load the native entry point for this app
           load()
       }
       // Enable logging for debugging (remove in production)
       RNBranchModule.enableLogging();
       ReactNativeFlipper.initializeFlipper(this, reactNativeHost.reactInstanceManager)
   }
   ```

## 4. Track Link Parameters in App

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

```tsx
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 and start tracking referrals!

For that, you will need 2 things:

1. Universal Link
2. Your Integrated App

The RH SDK Pulls information from your Device, like this:

```jsx
final referralParams = {
  'email': 'user@example.com', // Capture this from user
  'hosting_url': 'https://a.domain.co/', // Optional value, and set as default by admin
  'name': 'User Name', // Capture this from user
  'referrer': 'referrerCode', // Optional value, Get from the deep link as referral_code. only necessary if you want to capture the referrer code from user
  'uuid': 'MF*******', // Get this from RH Dashboard
  'device': getDeviceType(), // Get device type
  'os_type': getOperatingSystem(), // Get operating system type
  'visitor_id': sub_********, // Get this from the deep link params
  'status': 'custom_event_pending' //Use 'custom_event_pending' to set the referral status to pending
};
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://berylsystems.gitbook.io/referral-hero-documentation/integrations/mobile-sdks/react-native/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.