Singular Cloud Mode Integration

RudderStack supports server-to-server (S2S) API integration with Singular. See the Singular API endpoint reference for more information.

RudderStack uses Singular’s API v2 when the event contains the Singular Device ID (SDID). Otherwise, it uses API v1 with platform-specific identifiers.

See Integration Setup Approaches to choose the right setup for your use case.

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 Session Event Name dashboard setting.

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

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

• Application Installed
• Application Opened
• Application Updated

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

Common mappings

These session event mappings apply regardless of which Singular API version (v1 or v2) RudderStack uses to send events.

Attributes automatically captured by RudderStack

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

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.

For mobile SDKs, you can leverage Transformations to anonymize IPs when sending events in cloud mode.

Attributes to pass via 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.

Attributes to pass via event properties just once

The following table lists the mapping of the attributes that must be passed via the event properties just once — the RudderStack SDK persists these properties.

For more information on setting the device token, see the Android (Java) or iOS (Obj-C) SDK documentation.

Identifier mappings

The following identifiers are automatically captured by RudderStack:

The following identifier must be passed via the event properties with every event (not persisted in the SDK):

The following identifiers must be passed via the event properties just once (persisted in the SDK):

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

Custom events

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

Common mappings

These custom event mappings apply regardless of which Singular API version (v1 or v2) RudderStack uses to send events.

Attributes automatically captured by RudderStack

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

Attributes to pass via event properties

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

Attributes to pass via event properties just once

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

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.

Identifier mappings

The Singular API version RudderStack uses depends on the identifier fields in the events.

If the Singular device ID (SDID) is present in the event, RudderStack automatically uses the Singular API v2 and ignores the traditional platform-specific identifiers like idfa, andi, idfv, and aifa.

Otherwise, it falls back to the platform-specific identifiers and sends the events using the Singular API v1.

Pass the Singular device ID and data sharing options

To send the Singular Device ID and data sharing options, include singularDeviceId and limitDataSharing within your event’s integrations object, as shown:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {
    integrations: {
      Singular: {
        singularDeviceId: "<SINGULAR_DEVICE_ID>",
        limitDataSharing: true  // optional
      }
    },
  }
);

analytics.track(
    name = "Order Completed",
    properties = Properties(mapOf(
        "revenue" to 30,
        "currency" to "USD",
        "user_actual_id" to 12345
    )),
    options = RudderOption(
        integrations = buildJsonObject {
            put(
                "Singular",
                buildJsonObject {
                    put("singularDeviceId", "<SINGULAR_DEVICE_ID>")
                    put("limitDataSharing", true) // optional
                }
            )
        }
    )
)

String eventName = "Order Completed";

Map<String, Object> propertiesMap = new LinkedHashMap<>();
propertiesMap.put("revenue", 30);
propertiesMap.put("currency", "USD");
propertiesMap.put("user_actual_id", 12345);
Properties properties = new Properties(propertiesMap);

// Singular integration options
Map<String, Object> singularOptions = new LinkedHashMap<>();
singularOptions.put("singularDeviceId", "<SINGULAR_DEVICE_ID>");
singularOptions.put("limitDataSharing", true); // optional

// Integrations map
Map<String, Object> integrations = new LinkedHashMap<>();
integrations.put("Singular", singularOptions);

// Build options
RudderOption option = new RudderOptionBuilder()
        .setIntegrations(integrations)
        .build();

// Track event
analytics.track(eventName, properties, option);

analytics.track(
    name: "Order Completed",
    properties: [
        "revenue": 30,
        "currency": "USD",
        "user_actual_id": 12345
    ],
    options: RudderOption(
        integrations: [
            "Singular": [
                "singularDeviceId": "<SINGULAR_DEVICE_ID>",
                "limitDataSharing": true // optional
            ]
        ]
    )
)

RSSOptionBuilder *optionBuilder = [[RSSOptionBuilder alloc] init];

[optionBuilder setIntegrations:@{
    @"Singular": @{
        @"singularDeviceId": @"<SINGULAR_DEVICE_ID>",
        @"limitDataSharing": @YES // optional
    }
}];

NSDictionary *properties = @{
    @"revenue": @30,
    @"currency": @"USD",
    @"user_actual_id": @12345
};

[analytics track:@"Order Completed"
       properties:properties
          options:[optionBuilder build]];

client.track({
  userId: "1hKOmRA4GRlm",
  event: "Order Completed",
  properties: {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345,
  },
  integrations: {
    Singular: {
      singularDeviceId: "<SINGULAR_DEVICE_ID>",
      limitDataSharing: true, // optional
    },
  },
});

The resulting track payload contains the Singular device ID (SDID) and data sharing options in the integrations object, as shown:

{
  "type": "track",
  "event": "Order Completed",
  "properties": {
    "revenue": 30,
    "currency": "USD",
    "user_actual_id": 12345
  },
  "integrations": {
    "Singular": {
      "singularDeviceId": "<SINGULAR_DEVICE_ID>",
      "limitDataSharing": true
    }
  }
}

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. In your Singular dashboard, navigate to Developer Tools > Testing Console.

2. To add a new device to track, click the Add Device option and choose the relevant settings:

3. You should see a list of tracked devices, as seen below:

4. Select the tracked device from the list to see the events in real-time.

See the Singular documentation for more information on using the console for testing and validating your Singular integration.

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.