Getting Started

React Native API Integration

Overview

The ReferralHero API is organized around REST. Our API has predictable, resource-oriented URLs. JSON is returned by all API responses, including errors.

Base URL

Calls for ReferralHero API are relative to the URL

https://app.referralhero.com/api/sdk/v1/

Request Headers

1. Authorization - Your access token

2. Accept - application/vnd.referralhero.v1

3. Content-Type - application/json

To summarize, your request headers should look like this

{ 
   'Content-Type': 'application/json',
   'Accept': 'application/vnd.referralhero.v1',
   'Authorization': 'xxxxxxxxxx'
 }

Getting started

Step 1: Set Up Your Project

1. Open your React Native project.

2. Install a library for making HTTP requests, such as axios or use the built-in fetch API.

Step 2: Make Your First API Call

1. Import your HTTP library:

import axios from 'axios';

1. Set up your API call:

const apiUrl = 'https://app.referralhero.com/api/sdk/v1/';
const apiToken = 'Your-api-token';

axios.get(`${apiUrl}endpoint`, {
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/vnd.referralhero.v1',
    'Authorization': apiToken
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error making API call', error);
});

Step 3:

1. Get your API_TOKEN from the ReferralHero Dashboard -> API: ReferralHero Dashboard.

1. Back in the ReferralHero overview, click to edit your desired Campaign.

1. Then the Installation tab, then Mobile App Installation.

1. Get your UUID: The 12-letter ID that starts with ‘MF’ in Edit Campaign > launch > Mobile app installation, e.g. MFxxxxxxxxxx.

1. Add the Campaign Token obtained from the campaign, and UUID from the installation Tab.

Step 4:

In the Goal section of your Campaign settings, ensure you have added the Google Play and Apple App Store links and a default referral link for desktop web users.

Well done! You should now be able to build and run your campaign. Before using the more advanced features of the API, you should learn about a couple of important concepts.

Tracking Referrals

Now that you have implemented the SDK, you can start identifying and 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:

final referralParams = {
  'email': '[e-mail]', // Capture this from user
  'domain': 'https://a.domain.co/', // Optional value, and set as default by admin
  'name': 'User Name', // Capture this from user
  'referrer': 'referrerCode', // Optional value, only necessary if you want to capture the referrer code from user
  'uuid': 'MFxxxxxxxxx', // Get this from RH Dashboard
  'device': getDeviceType(), // Get device type
  'ip_address': ipAddress, // Get IP address
  'os_type': getOperatingSystem(), // Get operating system type
  'screen_size': transformResolution(getDeviceScreenSize()), // Get screen size
  'status': 'custom_event_pending' //Use 'custom_event_pending' to set the referral status to pending
};

Helper Functions

Get Device Type

You can use the react-native-device-info library to get the device type.

import DeviceInfo from 'react-native-device-info';

function getDeviceType() { 
  let deviceType = "Desktop";
  if (Platform.OS === 'ios') 
    { if (DeviceInfo.getModel().toLowerCase().includes("ipad")) { 
      deviceType = "iPad"; 
    } else if (DeviceInfo.getModel().toLowerCase().includes("ipod")) {
       deviceType = "iPod"; 
    } else { deviceType = "iPhone"; } 
  } else if (Platform.OS === 'android') { 
    deviceType = "Android"; 
  } else if (Platform.OS === 'windows') { 
    deviceType = "Windows Phone"; 
  } else if (Platform.OS === 'blackberry') {
     deviceType = "BlackBerry"; 
  } else { 
    deviceType = "Unknown Device";
  } 
  return deviceType; 
}

Get IP Address

const [ipAddress, setIpAddress] = useState('');

  useEffect(() => {
    getIpAddress();
  }, []);

  const getIpAddress = async () => {
    try {
      const response = await fetch('https://api.ipify.org?format=json');
      const data = await response.json();
      setIpAddress(data.ip);
    } catch (error) {
      console.error("Failed to fetch IP address:", error);
    }
  };

Get Operating System

You can use the Platform module from React Native to get the operating system type.

import { Platform } from 'react-native';
​
function getOperatingSystem() {
  return Platform.OS; // Returns 'ios' or 'android'
}

Get Device Screen Size

You can use the Dimensions module from React Native to get the screen size.

import { Dimensions } from 'react-native';
​
function getDeviceScreenSize() {
  const screenWidth = Dimensions.get('window').width;
  const screenHeight = Dimensions.get('window').height;
  return `${screenWidth} x ${screenHeight}`;
}

Adding the Subscriber Data

With this information, you should be able to add the subscriber data using the addSubscriber method to automatically identify or track a referral:

function formSubmit() {
  axios.post(`https://app.referralhero.com/api/sdk/v1/lists/MFxxxxxxxxx/subscribers`, referralParams, {
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/vnd.referralhero.v1',
      'Authorization': apiToken
    }
  })
  .then(response => {
    console.log('Subscriber added successfully:', response.data);
  })
  .catch(error => {
    console.error('Error adding subscriber', error);
  });
}

Embedding ReferralHero Widget in React Native WebView

1. Identify the Subscriber Using the API

To begin, call the Add Subscriber Endpoint using the following endpoint:

Endpoint: https://app.referralhero.com/api/sdk/v1/lists/UUID/subscribers

Send the necessary mobile parameters and subscriber details. The API response will include a subscriber ID, which is required for authentication. It is crucial to store the subscriber ID securely as it will be used for future authentication. Make sure that the API call is handled properly and errors are logged for debugging.

2. Set Authentication Cookies in the WebView

Before loading the widget, ensure the WebView injects the subscriber ID as a cookie. These cookies allow the widget to automatically recognize the user without requiring manual authentication. This step helps in reducing friction for users, enabling a smoother experience without the need for repeated logins.

3. Embed the Widget Inside a WebView

The RH-hosted page, containing the widget, should be loaded within a WebView inside the React Native app. This ensures that the widget functions exactly as it does in a standard browser environment. Additionally, ensure that WebView settings allow JavaScript execution and storage access, which is necessary for proper widget functionality.

4. Auto-Redirect to the Share Screen

Once the widget detects the authentication cookies, it will bypass the login screen and directly load the share screen. This creates a seamless user experience, similar to accessing the widget from a logged-in web browser.

To further enhance user experience, consider adding loading indicators while the WebView is initializing to inform users of ongoing processes.

Implementation

import React, { useEffect, useState, useRef } from 'react';
import { View, StyleSheet, Alert } from 'react-native';
import { WebView } from 'react-native-webview';
import AsyncStorage from '@react-native-async-storage/async-storage';

const ReferralWidget = () => {
  const webViewRef = useRef(null);
  const [injectedJS, setInjectedJS] = useState('');

  useEffect(() => {
    const fetchId = async () => {
      const id = await AsyncStorage.getItem("id");
      if (id) {
        const script = `
          document.cookie = "__maitre-anonymous-MFxxxxxxxxx=${id}; path=/; max-age=86400";
          document.cookie = "__maitre-session-MFxxxxxxxxx=${id}; path=/; max-age=86400";
          window.ReactNativeWebView.postMessage(document.cookie);
        `;
        setInjectedJS(script);
      }
    };
    fetchId();
  }, []);

  const handleMessage = (event) => {
    //Alert.alert("Cookies", event.nativeEvent.data);
  };

  return (
    <View style={styles.container}>
      {injectedJS ? (
        <WebView 
          ref={webViewRef}
          source={{ uri: 'https://campaign.referralhero.com/MFxxxxxxxx/dashboard' }}
          javaScriptEnabled={true}
          domStorageEnabled={true}
          startInLoadingState={true} 
          onLoadEnd={() => console.log("WebView Loaded Successfully")}
          injectedJavaScript={injectedJS}
          onMessage={handleMessage}
        />
      ) : null}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  }
});

export default ReferralWidget;

This implementation ensures that the subscriber authentication process is seamless, automatically logging users into the referral widget inside the React Native WebView.