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 'https://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" />

   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="com.google.android.gms.permission.AD_ID" />

3. If you have disabled transitive dependencies for the Singular SDK, add the following to your app's build.gradle.

   implementation 'com.android.installreferrer:installreferrer:2.2'
   implementation 'com.google.android.gms:play-services-appset:16.0.0'

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, 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(config);

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>")
       .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.

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

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
config.withSkAdNetworkEnabled(true);

// Wait 5m for tracking authorization before sending any events
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

Singular.init(config);