Singular Cloud Mode Integration

Send events from RudderStack to Singular via cloud mode.

RudderStack supports server-to-server (S2S) API integration with Singular.

info
Refer to the Singular documentation for the Singular API endpoint reference.

RudderStack supports two types of track events that you can send to Singular via cloud mode:

  • Session events
  • Custom events

Session events

RudderStack lets you specify the event names to be used as session events in the dashboard settings:

Singular session events settings

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

warning

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

  • Application Installed
  • Application Opened
  • Application Updated
info
RudderStack automatically tracks the above three lifecycle events if lifecycle event tracking is enabled.

Supported mappings

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 propertySingular attributeDescription
context.os.name
Required
pThe source platform (Android or iOS).
context.app.namespace
Required
iThe package name (Android) or bundle ID (iOS) of your app.
context.app.version
Required
app_vThe app version.
context.ip
request_ip (in that order)
Required
ipThe user’s IP address. Refer to the note below for information on anonymizing your IP.
context.os.version
Required
veThe device OS version at session time.
context.device.model
Required
moThe device model. This parameter must be used with the ma parameter.
context.device.manufacturer
Required
maThe make of the device hardware. This parameter must be used with the mo parameter.
context.locale
Required
lcThe device’s IETF local tag using two-lettered language and country code, separated by an underscore.
context.device.id
Required
idfvThe raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.id
Required, if context.device.advertisingId and properties.asid is absent.
andiThe 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. See FAQ for more information.
context.app.build
Required
bdThe device build (URL encoded).
context.device.adTrackingEnabled
Required
dntPass 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.namenThe human-readable app name as displayed in the UI.
utimeOptional
context.network.wificThe connection type (WiFi or carrier).
context.network.carriercnThe carrier name of the internet provider.
success
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 case of mobile SDKs, you can leverage the Transformations feature to do this - when sending events via cloud mode.

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

warning
These properties are not persisted in the SDK and must be passed with every event.
RudderStack propertySingular attributeDescription
properties.install_ref
Required
install_refThe Google Install Referrer Information.
properties.referring_application
Required
install_sourceThe install source package name in Android. Use getInitiatingPackageName() to retrieve this.
properties.install_receipt
Required
install_receiptThe receipt received from the install. To retreive this, follow the iOS Install Receipt guide.
properties.asid
Required, if context.device.advertisingId and context.device.id is absent.
asidThe App Set ID for Android v12+ devices. See FAQ for more information.
properties.url
Required
openuiIf the app is opened via a deep link/universal link, the value of the encoded deep link URL.
context.device.attTrackingStatus
Required
att_authorization_statusThe App Tracking Transparency authorization status.
userIdcustom_user_idThe user ID passed through the identify call.
properties.attribution_tokenattribution_tokenUsed to attribute Apple Search Ads for iOS 14.3 and above. More information here.
properties.skan_conversion_valueskan_conversion_valueThe latest SkAdNetwork value at the time of the session notification.
properties.skan_first_call_timestampskan_first_call_timestampUNIX timestamp of the first call made to the SkAdNetwork API.
properties.skan_last_call_timestampskan_last_call_timestampUNIX timestamp of the last call made to the SkAdNetwork API at the time of the session notification.
properties.installinstallThe install flag. Set to true on the first session after app install, or false otherwise. Required for reinstall tracking capability.

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

info
These properties are persisted in the SDK and must be passed just once.
RudderStack propertySingular attributeDescription
context.device.advertisingId
Required
idfaThe raw advertising ID in upper case with dashes. This is applicable for iOS apps only.
context.device.advertisingId
Required, if properties.asid and context.device.id is absent.
aifaThis is the lower case raw advertising ID with dashes. This is applicable for Android apps only. See FAQ for more information.
context.device.tokenfcmThe Firebase Cloud Messaging Device Token. It is required for uninstall tracking in Android.
context.device.tokenapns_tokenThe Apple Push Notification Service Device Token. It is required for uninstall tracking in iOS.
info
For more information on setting the device token, refer to the Android or iOS SDK documentation.
info
RudderStack supports only fcm for mapping the device token.

Custom events

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

Supported mappings

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

RudderStack propertySingular attributeDescription
context.os.name
Required
pThe source platform (Android or iOS).
context.app.namespace
Required
iThe package name (Android) or bundle ID (iOS) of your app.
context.ip
request_ip (in same order)
Required
ipThe user’s IP address.
context.device.advertisingId
Required
idfaThe raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.advertisingId
Required, if properties.asid and context.device.id are absent.
aifaThis is the lower case raw advertising ID with dashes. This is applicable for Android apps only. See FAQ for more information.
context.device.id
Required
idfvThe raw IdentifierForVendor in upper case with dashes. This is applicable for iOS apps only.
context.device.id
Required, if context.device.advertisingId and properties.asid are absent.
andiThe 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. See FAQ for more information.
context.os.version
Required
veThe device OS version at session time.
utimeOptional
info
Singular prefers aifa over andi (in Android) and idfa over idfv (in iOS).

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

RudderStack propertySingular attributeDescription
event
Required
nThe name of the event. This is user-defined.
context.device.attTrackingStatus
Required
att_authorization_statusThe App Tracking Transparency authorization status.
userIdcustom_user_idThe user ID passed through the identify call.
properties.skan_conversion_valueskan_conversion_valueThe latest SkAdNetwork value at the time of the session notification.
properties.skan_first_call_timestampskan_first_call_timestampUNIX timestamp of the first call made to the SkAdNetwork API.
properties.skan_last_call_timestampskan_last_call_timestampUNIX timestamp of the last call made to the SkAdNetwork API at the time of the session notification.
properties.eventAttributeseThe 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_eventis_revenue_eventDetermines 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.

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

RudderStack propertySingular attributeDescription
properties.total
properties.value
properties.revenue
amtThe currency amount.
properties.currencycurThe ISO 4217 three-lettered currency code. This should be in conjunction with the amt parameter.
properties.purchase_receiptpurchase_receiptThe receipt received from a purchase.
properties.product_id
properties.sku
purchase_product_idThe product SKU identifier.
properties.orderId
properties.purchase_transaction_id (in that order)
purchase_transaction_idThe transaction identifier.
info
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.

FAQ

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:

  1. Go to Settings > Console. You should see a list of tracked devices:
Singular event delivery settings
  1. To add a new device, click the Add Device option and choose the relevant settings:
Singular event delivery settings
  1. Finally, click the eye icon associated with the tracked device to start seeing the events in real-time.
Singular event delivery settings

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

Singular event delivery settings
info
For more customizable and granular reports, you can go to Attribution > Export Logs in the Singular dashboard. Note that this report is not real-time and takes some time to generate.

Which device ID attributes are required for Android?

For Android requests, Singular requires either of the following attributes in the mentioned order of preference:

  • aifa
  • asid
  • andi

If none of them are available, you must send at least one with the empty value (instead of null or undefined). If you send all of them, RudderStack discards the andi attribute as per Google’s data policies.


Questions? Contact us by email or on Slack