React Native SDK: Basic Integration

Singular React Native SDK
Singular React Native SDK version 3.2.2 (see Change Log)
Compatibility React Native 0.46.4+
Sample App

Our sample app includes a complete integration of the Singular SDK. Review the code to see how the different parts of the integration come together using best practices.

Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options


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 inside allprojects section, add the following to your app's Maven repositories:

    allprojects {
        repositories {
          maven { url '' }
  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="" />
     <!--  This permission is needed for Singular to retrieve data from the google licensing API  -->
     <uses-permission android:name="" />

    If your app build is targeting Android 12/API level 31 or higher, add permissions to access the Google Advertising ID:

    <uses-permission android:name="" />
  3. If you have disabled transitive dependencies for the Singular SDK, add the following to your app's build.gradle.
    implementation ''
    implementation ''

Initializing the SDK

Note: Remember to remain compliant with the various privacy laws enacted in regions where doing business, including but not limited to GDPR, CCPA and COPPA when implementing the Singular SDKs. For more information, see SDK Opt-In and Opt-Out Practices.

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, Events, Attributes} 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 SDK key and SDK secret (you can get them by logging into your Singular account and going to Developer Tools > SDK Keys).

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('<SDK KEY>', '<SDK SECRET>');

// Optional settings:
// Set user ID if known at time of initialization config.withCustomUserId("274e9db5c836093499df921be5b7f32001d49c50");
// Enables deep linking
config.withSingularLinks(callBackFunction); Singular.init(config);
Singular.init Method
Description Initialize the Singular SDK.
Usage Example

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("<SDK KEY>", "<SDK SECRET>")
  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.unsetCustomUserId Method
Description Unset the user ID in Singular.
Usage Example

Handling AppTrackingTransparency Consent

Starting with iOS 14.5, you are required to ask for user consent (using ATTrackingManager) before you can access the device's IDFA for tracking.

If you want to initialize the Singular SDK before you ask the user for consent, you can delay the SDK from firing events without IDFA for a specified interval of time, in order to wait for user consent.

To do so, initialize the Singular SDK with the waitForTrackingAuthorizationWithTimeoutInterval option, as in the following example:

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

// Enable SKAdNetwork

// Wait 5m for tracking authorization before sending any events