Singular Device Mode

Step-by-step guide on sending events from RudderStack to Singular via the device mode.

RudderStack lets you send your events to Singular via device mode using the mobile SDKs.

Adding device mode integration

After you set up Singular as a destination in RudderStack, follow these steps to add it to your project, depending on your platform of integration.

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

In your Podfile, add the following dependencies:

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

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>
```

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

For more information, refer to the Singular iOS documentation.

This device mode integration is supported for Singular v11.0.4 and above.

Follow these steps to add Singular to your iOS project:

Install RudderSingular (available through CocoaPods) by adding the following line to your Podfile:
```
pod 'RudderSingular', '~> 1.0.0'
```
Run the pod install command.
Next, import the SDK depending on your preferred platform:
```
import RudderSingular
```
```
@import RudderSingular;
```

Next, add the imports to your AppDelegate file under the didFinishLaunchingWithOptions method, as shown:

let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)        

RSClient.sharedInstance().configure(with: config)
let rudderSingularConfig = RudderSingularConfig()
            .skAdNetworkEnabled(true)
            .manualSkanConversionManagement(true)
            .conversionValueUpdatedCallback({ value in
                print("Your SKAN handler \(value)")
            })
            .waitForTrackingAuthorizationWithTimeoutInterval(0)
RSClient.sharedInstance().addDestination(RudderSingularDestination(rudderSingularConfig: rudderSingularConfig))

RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];

[[RSClient sharedInstance] configureWith:config];
RudderSingularConfig *rudderSingularConfig = [[RudderSingularConfig alloc] init];
[rudderSingularConfig skAdNetworkEnabled:YES];
[rudderSingularConfig manualSkanConversionManagement:YES];
[rudderSingularConfig conversionValueUpdatedCallback:^(NSInteger value) {
    printf("Your SKAN handler %ld", value);
}];
[rudderSingularConfig waitForTrackingAuthorizationWithTimeoutInterval:0];
[[RSClient sharedInstance] addDestination:[[RudderSingularDestination alloc] initWithRudderSingularConfig:rudderSingularConfig]];

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

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'

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

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"/>

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()
  )

For more information, refer to the Singular Android documentation.

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

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

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

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

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:

Navigate to the root folder of your application and run the following command:
```
cordova plugin add rudder-integration-singular-cordova
```

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]
})

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

Identify

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

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

[[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:

[[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:

[[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:

[[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:

[[RSClient getInstance] reset];

RudderClient.getInstance()?.reset();

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.

Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.