Before You Begin: SDK Prerequisites

Follow the steps in Integrating a Singular SDK: Planning and Prerequisites.

These steps are prerequisites for any Singular SDK integration.

Install the SDK

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

4. If you are using Expo: After installing the Singular SDK as described above, add the package to the plugins array of your app.json or app.config.js:  

   "expo": {
     "plugins": ["singular-react-native"]
   }

   Then rebuild your app using Expo's guide for customizing native code. 

Setting Up Prerequisites

iOS Prerequisites

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

cd ios; pod install

Android Prerequisites

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/' }
  }
}

Add the following permissions to your app’s AndroidManifest.xml file:

<!-- Permission to access the internet -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Permission to access network state -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Permission needed to retrieve Google Play Referrer data -->
<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />
<!-- Permission needed to retrieve data from the Google licensing API -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<!-- Permission to access the Google Advertising ID (for Android 12/API level 31 or higher) -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

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'

Integrate 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 the Singular Library

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';

Initializing the Singular SDK

1. 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 Integration > SDK Keys").
2. Optionally, you can add settings to enable various SDK features.
3. META Install Referrer Attribution Support

   Required SDK configuration to enable "Meta Install Referrer" attribution:

   1. Provide your Facebook App Id in the Singular Configuration Object.
      

      // To enable META Install Referrer
      config.withFacebookAppId('INSERT YOUR FACEBOOK APP ID HERE');

   Where can I find an app's Facebook App ID?
4. 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('274e9db5c836093499df921be5'); 
// To enable META Install Referrer
 config.withFacebookAppId('Insert your Facebook App ID here');
// Enables deep linking
 config.withSingularLink(callBackFunction); 
// iOS - Enable SKAdNetwork
 config.withSkAdNetworkEnabled(true);  
// iOS - Wait 5m for tracking authorization before sending any events
 config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  
 Singular.init(config);

Singular.init(config);