Rudderstack - Singular Destination (Device-Mode)

RudderStack is an open-source customer data platform (CDP) that enables businesses to collect, unify, and route customer data to various destinations. It provides a centralized platform for managing customer data pipelines, allowing organizations to easily collect data from various sources such as websites, mobile apps, servers, and cloud services.

The Singular SDK is available as a plug-in for Rudderstack, referred to as a "Device-Mode" Destination. The instructions below illustrate how to add the Singular Destination in Rudderstack.

Be advised that this integration is built and maintained by Rudderstack. Please consult with Rudderstack if issues occur during implementation.

Guide for Engineering Teams
Prerequisites This article assumes you already have the Rudderstack iOS, Android, React Native, or Cordova SDK integrated in your app. See Rudderstack documentation for more details about device-mode and the mobile SDKs.

To use this integration, you must be using Rudderstack's Mobile SDK for: iOS (Native Obj-C or Swift), Android (Java or Kotlin), React Native, or Cordova. This integration is NOT compatible with any other framework!

What's Supported
  1. Basic Install Attribution
  2. SkAdNetwork Support
  3. Apple Search Ads Attribution
  4. Custom In-App Event Tracking
  5. Revenue tracking
  6. Custom User ID
What's NOT Supported
  1. META Install Referrer Attribution
  2. Deep linking
  3. Limited Data Sharing Support

If you need support for another Frameworks or would like "Full Feature Functionality" offered by the Singular SDK, you must implement the Singular SDK independently from Rudderstack. See the SDK Options and Frameworks HERE.

Getting Started

  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 Continue.

Connection settings

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

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

    Get your Singular "SDK KEY", found in the Singular Dashboard under "Developer Tools > SDK Integration > SDK Keys".

    Note: For the "Cloud-Mode" integration, you will ONLY input the API Key(SDK Key) value.
    Leave the "Secret" blank.

  • Session Event Name: This setting is applicable only for sending events via cloud mode.
  • Use device mode to send events: When using the Android or iOS platforms, you can enable this setting to send events via device mode. Then, follow the Singular Device Mode guide for steps on adding Singular to your project.

    When sending events via 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 guide.

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.

iOS iOS v2 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> #import <ruddersingularfactory.h>
  3. Initialize your RSClient:


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


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

iOS (Obj-C) Android (Kotlin)
[[RSClient getInstance] identify:@"1hKOmRA4el9Zt1WSfVJIVo4GRlm"];


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 (Obj-C) Android (Kotlin)
[[RSClient getInstance] track:@"Product Reviewed" properties:@{
        @"product_id" : @"345676543",
        @"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 (Obj-C) Android (Kotlin)
[[RSClient getInstance] track:@"Order Completed" properties:@{
        @"revenue" : @1251,
        @"currency" : @"INR"


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 (Obj-C) Android (Kotlin)
[[RSClient sharedInstance] screen:@"Home" properties:@{
    @"category" : @"launcher"

In the above snippet, RudderStack captures all 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.


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 (Obj-C) Android (Kotlin)
[[RSClient 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:


  • Setting the manualSkanConversionManagement = true will require you to manually update your own Conversion Values. This will NOT allow for Singular's SKAN Model to update the CV values on your behalf. Set this to "false" to enable "managed" mode.
  • Setting the waitForTrackingAuthorizationWithTimeoutInterval should only be used if your app uses the iOS App Tracking Transparency(ATT) Prompt. If you are displaying ATT, then this should be set to a value of 300.


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