Integrating Singular SDK with React Native: A Comprehensive Guide

Singular is a powerful marketing analytics platform that helps track user behavior, measure ROI, and optimize campaigns. Integrating Singular with a React Native project can provide robust user analytics and tracking capabilities. This guide will walk you through the integration process, including initializing Singular, handling uninstall events, registering events, and tracking revenue.

---

Prerequisites

Before you begin, ensure the following:

1. Your project is set up with React Native.
2. Singular SDK is installed and configured for both iOS and Android platforms.
3. Required API keys and secrets are obtained from the Singular dashboard.

---

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

• 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

• 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"]
}

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'

1. Initializing the Singular SDK

The initializeSingular function configures and initializes Singular. Here's the implementation:

export const initializeSingular = async () => {
  try {
    const singularConfig = new SingularConfig(
      SINGULAR_API_KEY,
      SINGULAR_API_SECRET
    ).withCustomUserId(YOUR_USER_ID);

    trackingUninstallEvent();

    // Enable SKAdNetwork tracking (for iOS)
    try {
      singularConfig.skAdNetworkEnabled = true;
    } catch (error) {
      console.log('Error enabling SKAdNetwork:', error);
    }
    singularConfig.withSkAdNetworkEnabled(true);

    // Handle Singular Links for deep linking
    singularConfig.withSingularLink((singularLinksParams) => {
      const passthrough = singularLinksParams.passthrough;
      storage.set('passthrough', JSON.stringify(passthrough));
    });

    // Wait for tracking authorization
    singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

    // Initialize Singular
    Singular.init(singularConfig);
  } catch (error) {
    console.log('Error initializing Singular:', error);
  }
};

Key Points:

• Custom User ID: You can associate user-specific data with Singular.
• SKAdNetwork Support: Enables app tracking transparency for iOS.
• Deep Linking: Captures passthrough data for further processing.
• Timeout Interval: Configures the wait time for tracking authorization.

---

2. Tracking Uninstall Events

Singular supports tracking uninstalls by using device tokens. The trackingUninstallEvent function retrieves the device token and sends it to Singular:

export const trackingUninstallEvent = async () => {
  try {
    const fcmToken = YOUR_FCM_TOKEN;
    const apnToken = YOUR_APN_TOKEN; // you will get this from messaging().getAPNSToken(); from `@react-native-firebase/messaging`
    if (isIOS) {
      Singular.setUninstallToken(apnToken);
    } else if (isAndroid) {
      Singular.setUninstallToken(fcmToken);
    }
  } catch (error) {
    console.log('Error tracking uninstall event:', error);
  }
};

Key Points:

• FCM Token: Used for Android devices.
• APN Token: Used for iOS devices.
• Platform-Specific Logic: Ensures compatibility with both platforms.

---

3. Registering Singular Events

To track custom user interactions, use the registerSingularEvent function:

export const registerSingularEvent = (eventName, params = {}) => {
  try {
    Singular.eventWithArgs(eventName, params);
  } catch (error) {
    console.log('Error registering event:', error);
  }
};

Key Points:

• Event Name: Represents the action being tracked.
• Parameters: Additional metadata about the event.

---

4. Tracking Revenue Events

Singular allows tracking revenue from in-app purchases or other monetization strategies. The registerSingularRevenueEvent function handles this:

export const registerSingularRevenueEvent = (
  eventName,
  currency,
  revenue,
  params = {}
) => {
  try {
    Singular.customRevenueWithArgs(eventName, currency, revenue, params);
  } catch (error) {
    console.log('Error registering revenue event:', error);
  }
};

Key Points:

• Currency: ISO 4217 currency code.
• Revenue: Monetary value of the transaction.
• Additional Parameters: Contextual information about the revenue event.

---

5. Adding Deep Linking Support

Deep links are links that lead into specific content inside an app. When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Enabling Singular Links

To activate Singular Links on both iOS and Android platforms, refer to the Singular Links Prerequisites section and ensure the completion of the following requirements.

iOS Prerequisites

In the project’s AppDelegate.m, add the following

// Top of the AppDelegate.m
  #import <Singular-React-Native/SingularBridge.h>

  - (BOOL)application:(UIApplication *)application     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Add inside didFinishLaunchingWithOptions
      [SingularBridge startSessionWithLaunchOptions:launchOptions];
    return YES;
  }

  - (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
      restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
        [SingularBridge startSessionWithUserActivity:userActivity];
        return YES;
  }

Android Prerequisites

In the project’s MainActivity, add the following:

// Add as part of the imports at the top of the class
  import android.content.Intent;
  import net.singular.react_native.SingularBridgeModule;

  // Add to the MainActivity class
  @Override
  public void onNewIntent(Intent intent) {
    if(intent.getData() != null) {
      setIntent(intent);
      super.onNewIntent(intent);
      SingularBridgeModule.onNewIntent(intent);
    }
  }

Handling Singular Links

We utilize MMKV for local storage to save passthrough data from Singular Links:

export const storage = new MMKV();

// Handle Singular Links for deep linking
    singularConfig.withSingularLink((singularLinksParams) => {
      const passthrough = singularLinksParams.passthrough;
      storage.set('passthrough', JSON.stringify(passthrough));
    });

Key Points:

• Passthrough Data: Useful for deep linking and campaign analysis.
• Efficient Storage: MMKV provides fast and secure storage.

---

To ensure the initializeSingular function is called when your React Native app starts, you can invoke it in the App.js file. Here’s how you can do it:

import React, { useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { initializeSingular } from './path/to/your/singularIntegration'; // Update the path to your file

const App = () => {
  useEffect(() => {
    // Call initializeSingular when the app starts
    const init = async () => {
      await initializeSingular();
    };

    init();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Welcome to the App</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#fff',
  },
});

export default App;

Conclusion

Integrating Singular with React Native enables you to leverage advanced analytics and tracking capabilities. By following the steps outlined above, you can easily set up event tracking, revenue tracking, and uninstall event tracking to gain valuable insights into user behavior.

If you encounter issues during the setup or have additional use cases, consult Singular’s official documentation or reach out for support.