Rudderstack - Singular Destination (Cloud-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.

Singular may receive event data from Rudderstack over the Singular Server-to-Server (S2S) REST APIs for iOS and Android Mobile activity. This is referred to as a "Cloud-Mode" Destination. The instructions below illustrate how to add the Singular Destination in Rudderstack.

Guide for Engineering Teams
Prerequisites This article assumes you already have the Rudderstack iOS or Android SDK integrated into your app.

To use this integration, you must be using Rudderstack's Mobile SDKs. This integration is NOT compatible with Non-Mobile event data. Server or Web Events are not supported.

RudderStack supports two types of track events that you can send to Singular via "Cloud-Mode":

  • Session events
  • Custom events
What's Supported
  1. Basic Install Attribution
  2. Google Install Referrer Attribution
  3. SkAdNetwork Version 3 Support (Manual Mode)
  4. Apple Search Ads Attribution
  5. Custom In-App Event Tracking
  6. Revenue tracking
  7. Custom User ID
  8. Uninstall Tracking
What's NOT Supported
  1. SkAdNetwork Version 4 Support
  2. SkAdNetwork Managed Mode for Conversion Models
  3. META Install Referrer Attribution
  4. Deep linking
  5. Limited Data Sharing Support

If you need S2S support for the "Full Feature Functionality" offered by Singular, you must implement the Singular S2S REST APIs independently from Rudderstack. See the Server-to-Server (S2S) Integration Guide 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.

    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: Enter the event names to be used as session events. This setting is applicable only for sending events via cloud mode.

    RudderStack sends the session events to Singular via the Singular launch API.

    RudderStack considers an event as a session event only if it is specified in the dashboard settings or if it is one of the following three lifecycle events:

    • Application Installed
    • Application Opened
    • Application Updated

    RudderStack automatically tracks the above three lifecycle events if lifecycle event tracking is enabled.

  • Use device mode to send events: These toggles should be disabled when using "Cloud Mode". 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. 

Session Event Requirements

Supported SESSION Event Mappings

Attributes automatically captured by Rudderstack Mobile SDKs

This section lists the mappings of the RudderStack event properties to the relevant Singular fields.

The following table lists the mapping of the attributes automatically captured by RudderStack for the mobile platforms (Android and iOS):

RudderStack property Singular attribute Presence Description
context.os.name p Required The source platform (Android or iOS).
context.app.namespace i Required The package name (Android) or bundle ID (iOS) of your app.
context.app.version app_v Required The app version.
context.ip / request_ip (in that order) ip Required The user’s IP address. Refer to the note below for information on anonymizing your IP.
context.os.version ve Required The device OS version at session time.
context.device.model mo Required The device model. This parameter must be used with the ma parameter.
context.device.manufacturer ma Required The make of the device hardware. This parameter must be used with the mo parameter.
context.locale lc Required The device’s IETF local tag using two-lettered language and country code, separated by an underscore.
context.device.id idfv Required The raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.id andi Required The raw Android ID in lower case. This is applicable for Android apps only and is required only when the Android advertising ID is unavailable on the device.
context.app.build bd Required The device build (URL encoded).
context.device.adTrackingEnabled dnt Required Pass true if do not track(dnt) is disabled (dnt=0), else pass false(dnt=1). This is automatically captured if you pass the advertising ID to the SDK.
context.app.name n Optional The human-readable app name as displayed in the UI.
  utime Optional The session time (in UNIX time).
context.network.wifi c Optional The connection type (WiFi or carrier).
context.network.carrier cn Optional The carrier name of the internet provider.

To anonymize your IP, you can send a placeholder IP in the context.ip field. RudderStack uses it as the IP address instead of capturing it automatically from the backend. In the case of mobile SDKs, you can leverage the Transformations feature to do this - when sending events via cloud mode.

Attributes that must be passed via the event properties

The following table lists the mapping of the attributes that must be passed via the event properties:

These properties are not persisted in the SDK and must be passed with every event.

RudderStack property Singular attribute Presence Description
properties.install_ref install_ref Required The Google Install Referrer Information.
properties.referring_application install_source Required The install source package name in Android. Use getInitiatingPackageName() to retrieve this.
properties.install_receipt install_receipt Required The receipt received from the install. To retreive this, follow the iOS Install Receipt guide.
properties.asid asid Required The App Set ID for Android v12+ devices.
properties.url openui Required If the app is opened via a deep link/universal link, the value of the encoded deep link URL.
context.device.attTrackingStatus att_authorization_status Required The App Tracking Transparency authorization status.
userId custom_user_id Optional The user ID passed through the identify call.
properties.attribution_token attribution_token Optional Used to attribute Apple Search Ads for iOS 14.3 and above. More information here.
properties.skan_conversion_value skan_conversion_value Optional The latest SkAdNetwork value at the time of the session notification.
properties.skan_first_call_timestamp skan_first_call_timestamp Optional UNIX timestamp of the first call made to the SkAdNetwork API.
properties.skan_last_call_timestamp skan_last_call_timestamp Optional UNIX timestamp of the last call made to the SkAdNetwork API at the time of the session notification.
properties.install install Optional The install flag. Set to true on the first session after app install, or false otherwise. Required for reinstall tracking capability.
Attributes that must be passed via the event properties just once:

The following table lists the mapping of the attributes that must be passed via the event properties just once:

These properties are persisted in the SDK and must be passed just once.

RudderStack property Singular attribute Presence Description
context.device.token fcm Optional The Firebase Cloud Messaging Device Token. It is required for uninstall tracking in Android.
context.device.token apns_token Optional The Apple Push Notification Service Device Token. It is required for uninstall tracking in iOS.
context.device.advertisingId idfa Required The raw advertising ID in upper case with dashes. This is applicable for iOS apps only.
context.device.advertisingId aifa Required This is the lower case raw advertising ID with dashes. This is applicable for Android apps only.

For more information on setting the device token, refer to the relevant SDK documentation:

RudderStack supports only fcm for mapping the device token.

Custom Event Requirements

RudderStack sends all events other than the session events as custom events via Singular’s evt endpoint.

Supported EVENT Mappings

Attributes automatically captured by Rudderstack Mobile SDKs

This section lists the mappings of the RudderStack event properties to the relevant Singular fields.

The following table lists the mapping of the attributes automatically captured by RudderStack for the mobile platforms (Android and iOS):

RudderStack property Singular attribute Presence Description
context.os.name p Required The source platform (Android or iOS).
context.app.namespace i Required The package name (Android) or bundle ID (iOS) of your app.
context.ip / request_ip (in same order) ip Required The user’s IP address.
context.device.advertisingId idfa Required The raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.advertisingId aifa Required This is the lower case raw advertising ID with dashes. This is applicable for Android apps only.
context.device.id idfv Required The raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.id andi Required The raw Android ID in lower case. This is applicable for Android apps only and is required only when the Android Advertising ID is unavailable on the device.
context.os.version ve Required The device OS version at session time.
  utime Optional The session time (in UNIX time).

Singular prefers aifa over asid and asid over andi (in Android) and idfa over idfv (in iOS).

Attributes that must be passed via the event properties

The following table lists the mapping of the attributes that must be passed via the event properties:

These properties are not persisted in the SDK and must be passed with every event.

RudderStack property Singular attribute Presence Description
event n Required The name of the event. This is user-defined.
context.device.attTrackingStatus att_authorization_status Required The App Tracking Transparency authorization status.
userId custom_user_id Optional The user ID passed through the identify call.
properties.skan_conversion_value skan_conversion_value Optional The latest SkAdNetwork value at the time of the session notification.
properties.skan_first_call_timestamp skan_first_call_timestamp Optional UNIX timestamp of the first call made to the SkAdNetwork API.
properties.skan_last_call_timestamp skan_last_call_timestamp Optional UNIX timestamp of the last call made to the SkAdNetwork API at the time of the session notification.
properties.eventAttributes e Optional The custom event attributes in JSON format. You need to pass these with every event as they are not persisted in the SDK.
properties.is_revenue_event is_revenue_event Optional Determines if an event is a revenue event. You need to pass this through the properties with every event as it is not persisted in the SDK.
User-defined attributes specific to revenue events

The following table lists the mapping of the user-defined attributes specific to revenue events:

RudderStack property Singular attribute Presence Description
properties.total/ properties.value / properties.revenue amt Optional The currency amount.
properties.currency cur Optional The ISO 4217 three-lettered currency code. This should be in conjunction with the amt parameter.
properties.purchase_receipt purchase_receipt Optional The receipt received from a purchase.
properties.product_id/properties.sku purchase_product_id Optional The product SKU identifier.
properties.orderId / properties.purchase_transaction_id (in that order) purchase_transaction_id Optional The transaction identifier.

If you set any one out of the value, revenue, or total properties, RudderStack automatically considers the event as a revenue event, unless it is explicitly mentioned by the is_revenue_event property.

A few important considerations in case of custom events are listed below:

  • RudderStack takes the user agent from context.userAgent for Android and from the event properties in case of iOS.
  • RudderStack stores the extra attributes passed in the custom event in Singular’s e field.

Testing

How can I verify if the events are successfully delivered to Singular?

To verify if the events are successfully delivered to Singular, you can use RudderStack’s Destination live events feature.

You can also verify the event delivery by going to your Singular dashboard and following these steps:

Follow the detailed guide here on how to use the Testing Console

  1. Go to "Developer Tools > Testing Console".

  2. Click Add Device, and enter the relevant device identifier:

  3. You should be able to see a real-time log of all events sent to Singular: