React Native SDK: Basic Integration

 

Adding the SDK to Your Project

To add the Singular React SDK to your project:

  1. Open the terminal in the root directory of your project.
  2. Download the SDK package to your project with the following command:

    npm install singular-react-native --save
  3. If you are using React Native 0.60+, the Singular package will auto-link to your project.

    If you are using React Native version 0.59 or older, run the following to link the native bridge code from the Singular package to your project:

    react-native link singular-react-native

Setting Up Prerequisites

iOS Prerequisites

In the project’s root directory, run the following command:

cd ios; pod install

Android Prerequisites

  1. In the build.gradle file, add the following to your app's Maven repositories:

    maven { url 'http://maven.singular.net/' }
  2. Add the following permissions to your app’s AndroidManifest.xml file:

    <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <!--  This permission is needed for Singular to retrieve Google Play Referrer data  -->
     <uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />
     <!--  This permission is needed for Singular to retrieve data from the google licensing API  -->
     <uses-permission android:name="com.android.vending.CHECK_LICENSE" />

Initializing the SDK

The SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular. Sessions are used to calculate user retention.

Importing Required Classes

In your App.js file, add the following code to import the Singular and SingularConfigs classes.

import {Singular, SingularConfig} from 'singular-react-native';

Configuring and Initializing the SDK

Before you initialize the Singular SDK, you have to create a SingularConfig object. The object contains your API key and API secret for the Singular SDK (if you didn't get the key yet, see instructions). Optionally, you can add settings to enable various SDK features.

Then, use the init method to initialize the SDK, passing the SingularConfig object. For example:

const config = new SingularConfig('<API_KEY>', '<SECRET>');

// Optional settings
config.withCustomUserId("johndoe@email.com"); // Set user ID
config.withSingularLinks(callBackFunction); // Enable deep linking

Singular.init(config);
Singular.init Method
Description Initialize the Singular SDK.
Usage Example
Singular.init(config);

SingularConfig Options

".with" Method Description
withCustomUserId(user_id) Send the user idea to Singular (learn more)
withSingularLinks(callBackFunction) Enable deep linking (learn more)
withSessionTimeoutInSec(seconds) Modify the session timeout (learn more)

Optional: Setting the User ID

The Singular SDK can send a user ID from your app to Singular. This ID can be a username, email address, randomly generated string, or whichever identifier you use as a user ID.

Singular uses the user ID in user-level data exports as well as internal BI postbacks (if you configure such postbacks).

There are two ways to send the user ID to Singular:

  1. Recommended: If you know the user ID when the app opens, set the user ID as part of the SingularConfig object, before you initialize the SDK. This makes the user ID available to Singular from the very first session.

    const config = new SingularConfig("apikey","secret")
        .withCustomUserId("custom_user_id");
    Singular.init(config);
  2. Alternatively, you can call the setCustomUserId method at any point in the run.

In many cases, you will want to call setCustomUserId when the user logs in to your service, and call unsetCustomUserId if the user logs out.

Note: The user ID persists until you unset it using unsetCustomUserId or until the app is uninstalled. Closing/restarting the app does not unset the user ID.

Singular.setCustomUserId Method
Description Send the user ID to Singular.
Usage Example
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserId Method
Description Unset the user ID in Singular.
Usage Example
Singular.unsetCustomUserId();

 

Was this article helpful?