Singular

Step-by-step guide to send your event data from RudderStack to Singular

Singular is a marketing intelligence platform to transform your marketing data into accurate, granular, and actionable insights that drive growth.

RudderStack supports Singular as a destination to which you can seamlessly send your event data.

Getting started

Before configuring Singular as a destination in RudderStack, verify if the source platform is supported by Singular, by referring to the table below:

Connection Mode	Web	Mobile	Server
Device mode	-	Supported	-
Cloud mode	-	-	-

To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that the source platform supports sending events to Singular, follow these steps:

1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select Singular.

2. Assign a name to your destination and click on Next.

Connection settings

To successfully configure Singular as a destination, you need to configure the following settings:

• API Key: Enter your Singular API key here. This is a mandatory field.

• Secret: Enter your Singular secret. This is a mandatory field and is required for the device mode integrations with the RudderStack iOS and Android SDKs.

For more information on obtaining the Singular API key and secret, refer to the FAQ section below.

When sending events via the device mode, RudderStack also lets you specify which events should be discarded or allowed to flow through. For more information, refer to the Client-side Event Filtering.

Adding device mode integration

To add Singular to your application, follow the steps below depending on your platform of integration.

iOS Android React Native Cordova To add Singular to your iOS app, follow these steps:

1. In your Podfile, add the following dependencies:

   pod 'Singular-SDK', '11.0.4'
   pod 'Rudder-Singular', '1.0.0'

2. After adding the dependencies followed by pod install command, add the following imports to your AppDelegate.m file:

   #import <Rudder/Rudder.h>
   #import <RudderSingularFactory.h>

3. Then, initialize your RSClient, as shown:

   RSConfigBuilder *configBuilder = [[RSConfigBuilder alloc] init];
   [configBuilder withDataPlaneUrl:<DATA_PLANE_URL>];
   [configBuilder withFactory:[RudderSingularFactory instance]];
   RSClient *rudderClient = [RSClient getInstance:<WRITE_KEY> config:[configBuilder build]];

4. For more information, refer to the Singular iOS documentation.

To add Singular to your Android app, follow these steps :

1. Open your app/build.gradle (Module: app) file, and add the following under the dependencies section :

   implementation 'com.rudderstack.android.sdk:core:[1.0,2.0)'
   implementation 'com.rudderstack.android.integration:singular:1.0.0'
   implementation 'com.google.code.gson:gson:2.8.6'

2. Then, add the Singular Maven plugin to your build script. To do this, add the following snippet into the Gradle Scripts section of your root build.gradle:

   buildscript {
       repositories {
           google()
           mavenCentral()
           maven {
             url 'https://maven.singular.net/' 
           }
       }
       dependencies {
           classpath 'com.android.tools.build:gradle:7.1.2'
           classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
       }
   }
   allprojects {
       repositories {
           google()
           mavenCentral()
           maven {
             url 'https://maven.singular.net/' 
           }
       }
   }

3. Add the following permissions(if not present already) to your AndroidManifest.xml:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

4. Finally, initialize the RudderStack SDK in your Application class' onCreate() method, as shown:

   // initializing Rudder SDK
   val rudderClient = RudderClient.getInstance(
     this,
     <WRITE_KEY>,
     RudderConfig.Builder()
             .withDataPlaneUrl(<DATA_PLANE_URL>)
             .withFactory(SingularIntegrationFactory.FACTORY)
             .build()
     )

5. For more information, refer to the Singular Android documentation.

To add Singular to your React Native app, follow these steps:

1. Add the RudderStack-Singular module to your app by running the following command:

   npm install @rudderstack/rudder-integration-singular-react-native
   // OR //
   yarn add @rudderstack/rudder-integration-singular-react-native

2. Open your project-level android/build.gradle file and add the following snippet:

   repositories {
     maven {
       url "https://maven.singular.net/"
     }
   }

3. Then, import the above module and add it to your SDK initialization, as shown:

   import rudderClient from "@rudderstack/rudder-sdk-react-native"
   import singular from "@rudderstack/rudder-integration-singular-react-native"
   const config = {
   	dataPlaneUrl: <DATA_PLANE_URL>,
   	trackAppLifecycleEvents: true,
   	withFactories: [singular],
   }
   rudderClient.setup(<WRITE_KEY>, config)

To add Singular to your Cordova app, follow these steps:

1. Navigate to the root folder of your application and run the following command:

   cordova plugin add rudder-integration-singular-cordova

2. Then, add the following code in the onDeviceReady() function of your app's home page to initialize the SDK, as shown:

   RudderClient.initialize(<WRITE_KEY>, {
     dataPlaneUrl: <DATA_PLANE_URL>,
     factories: [RudderSingularFactory]
   })

3. Make sure you use the await keyword with the initialize call.

Implementing SKAdNetwork (SKAN) support

Add the following code before the initialization of the iOS SDK to give the control to Singular for your SKAdNetwork integration:

[RudderSingularIntegration setSKANOptions:YES
        isManualSkanConversionManagementMode:YES
withWaitForTrackingAuthorizationWithTimeoutInterval:@0
        withConversionValueUpdatedHandler:^(NSInteger conversionValue){
    // Receive a callback whenever the Conversion Value is updated
    NSLog(@"SKAN handler %ld",conversionValue);
}];

For more details, refer to the iOS SDK: Adding SKAdNetwork Support section of the Singular documentation.

Identify

For device mode destinations, the Singular SDK uses the identify method to map the RudderStack user ID to their custom user ID. RudderStack uses Singular's setCustomUserId method to forward the identified user ID to Singular.

A sample identify call for both the Android and iOS SDKs is shown below:

iOS Android

[[RSClient getInstance] identify:@"1hKOmRA4el9Zt1WSfVJIVo4GRlm"];

RudderClient.getInstance()?.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm")

Track

The track call lets you capture any user actions and the properties associated with them. Each user action is considered to be an event.

Tracking custom events

A custom track call lets you track custom events as they occur in your apps. RudderStack sends these calls to Singular where they are processed as custom post-install events and are made available in the relevant reports.

A sample custom track call for both the Android and iOS SDKs is shown below:

iOS Android

[[RSClient getInstance] track:@"Product Reviewed" properties:@{
        @"product_id" : @"345676543",
        @"review_id" : @"123454387"
    }];

RudderClient.getInstance()?.track("Product Reviewed",
    RudderProperty()
        .putValue("product_id", "345676543")
        .putValue("review_id", "123454387")
)

Tracking revenue

Singular supports tracking revenue events. It implements revenue tracking whenever an event containing the revenue property is sent(including a zero value). Optionally, you can also pass the currency field as an ISO code.

The default currency is set to USD.

A sample revenue track call is shown below:

iOS Android

[[RSClient getInstance] track:@"Order Completed" properties:@{
        @"revenue" : @1251,
        @"currency" : @"INR"
    }];

RudderClient.getInstance()?.track("Order Completed",
    RudderProperty()
        .putValue("revenue", 1251)
        .putValue("currency", "INR")
)

Screen

The screen method allows you to record whenever a user sees the mobile screen, along with any associated optional properties. This call is similar to the page call for the web applications but exclusive to your mobile device.

A sample screen call for both the Android and iOS SDKs is shown below:

iOS Android

[[RSClient sharedInstance] screen:@"Home" properties:@{
    @"category" : @"launcher"
}];

RudderClient.getInstance()?.screen("Home",
    RudderProperty()
        .putValue("category", "launcher")
)

In the above snippet, RudderStack captures all the information related to the viewed screen, along with any additional info about the screen.

RudderStack sends the screen event to Singular as a custom event.

Reset

The reset method resets the current user's identity and creates a new anonymous session. It should be called when a user logs out.

RudderStack calls Singular's unsetCustomUserId method to reset a user's identity.

A sample reset call for both the Android and iOS SDKs is shown below:

iOS Android

[[RSClient getInstance] reset];

RudderClient.getInstance()?.reset();

FAQ

Where can I find the Singular API key and secret?

To obtain your Singular API key and secret, log into your Singular dashboard and navigate to Settings > SDK Keys, as shown:

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.