Send Events to OneSignal (Device Model)

Send events to OneSignal via the Device Model API.

After you have successfully instrumented OneSignal as a destination in RudderStack, follow this guide to correctly send your events to OneSignal via their Device Model.

Find the open source transformer code for this destination in the GitHub repository.

danger

OneSignal device model is deprecated. RudderStack recommends sending events to OneSignal via their User Model API.

See the OneSignal documentation for more information.

Identify

You can make an identify call to add a new device to your OneSignal App. If a device is already registered with the specified identifier, then RudderStack updates the device records.

A sample identify call is shown:

rudderanalytics.identify('1hKOmRA4eGRlm', {
  firstName: 'Alex',
  lastName: 'Keener',
  email: "alex@example.com"
}, {
  externalId: [{
    type: "playerId",
    id: "Df344sdFgdDsS4"
  }],
  integrations: {
    oneSignal: {
      deviceType: "6",
      identifier: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    }
  }
});

In the above snippet, the playerId is the unique ID for a device. If playerId is provided in externalId, RudderStack updates the device having playerId. Note that for correct mapping, you must include externalId in your event in the exact format as shown above.

info
RudderStack adds the anonymousId as a tag with the key as anonymousId along with the corresponding value.

RudderStack maps the following browser and mobile device types by default:

deviceTypeMapping = {
    android: 1,
    ios: 0,
    chrome: 5,
    safari: 7,
    firefox: 8
}

You can override the above device type mappings or set any other device type by providing the deviceType and identifier in the integrations object:

"integrations": {
  "one_signal": {
    "deviceType": "Sample device",
    "identifier": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  }
}

For email and SMS, you can enable the Toggle on to add a device using email and Toggle on to add a device using phone number dashboard settings and send the relevant data (email or phone) in your events.

Property mapping

RudderStack maps the following optional properties to the corresponding OneSignal fields:

RudderStack propertyOneSignal property
context.device.modeldevice_model
context.os.versiondevice_os
context.timezonetimezone
userIdexternal_user_id
context.localelanguage
traits.createdAt
context.traits.createdAt
timestamp
originalTimestamp
created_at
last_active
traits.country
context.traits.country
traits.address.country
context.traits.address.country
country
integrations.one_signal.deviceTypedevice_type
integrations.one_signal.identifieridentifier

Note the following:

  • RudderStack maps all the string key-value pairs from traits in the tags object as is.

  • For browsers:

    • RudderStack checks the browser name in deviceTypeMapping and maps it to OneSignal’s device_type property.
    • It also sets the anonymousId as the identifier depending on the browser name.
  • For iOS and Android:

    • RudderStack collects the context.device.type field and maps it to OneSignal’s device_type property.
    • It also sets the context.device.token/context.device.id as the identifier.
info
RudderStack recommends sending the device.token property for push notifications.

Track

You can use the track call to update an existing device’s tags in your OneSignal apps using the external_user_id parameter. All devices containing the particular external_user_id are updated simultaneously.

info
To update the device tags using external_user_id, you must first identify the device using the identify call.

While updating a device tag, you can delete any key inside a tag by providing the key value as an empty string.

A sample track call is shown below:

rudderanalytics.track('Add to cart', {
    purchased_item: "Shirt",
    brand: "Adidas"
});

Property mapping

RudderStack maps the following properties to the corresponding OneSignal properties:

RudderStack propertyOneSignal property
userId
Required
external_user_id
info
RudderStack maps all properties added in the Allowed Property List dashboard setting to the tags object if they are present in the payload. However, note that the key-value pair should be of the String data type only.

Group

You can use the group call to group the devices with the device tags having the same groupId.

A sample group call is as shown:

rudderanalytics.group('1hKOmRA4GRlm', {
  name: "Apple Inc.",
  location: "USA",
});

Property mapping

The following table details the mappings between RudderStack and OneSignal properties:

RudderStack propertyOneSignal propertyPresence
groupIdgroupIdRequired
info
RudderStack maps all properties added in the Allowed Property List dashboard setting to the tags object if they are present in the payload. However, note that the key-value pair should be of the String data type only.

Questions? Contact us by email or on Slack