OneSignal

OneSignal is a popular service that helps you drive customer engagement with multi-channel messaging across web and mobile push notifications, in-app messages, SMS, and email subscribers.

RudderStack supports OneSignal as a destination where you can send your event data seamlessly.

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

Getting started

Before configuring OneSignal as a destination in RudderStack, verify if the source platform is supported by OneSignal by referring to the table below:

To learn more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that the source platform supports sending events to OneSignal, follow these steps:

1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select OneSignal.
2. Assign a name to the destination and click Continue.

Connection settings

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

• App Id: Enter your OneSignal App ID.

For more information on obtaining the OneSignal App ID, refer to the FAQ section below.

• Toggle on to add a device using email: Enable this setting to add a new device to your OneSignal app using the email.
• Toggle on to add a device using phone number: Enable this setting to add a new device to your OneSignal app using the phone number.
• Toggle on to concatenate event name with properties: Enable this setting to concatenate the event names with properties. For example, if add_to_cart is an event and brand is a property, the event will be sent as add_to_cart_brand tag.
• Allowed Property List: Enter the properties you want to add as the device tags, if present in the payload.

RudderStack considers the properties mentioned under Allowed Property List only for the track and group calls.

Identify

You can make an identify call to add a new device to your OneSignal App. However, if a device is already registered with the specified identifier, then it will update the existing device’s records.

A sample identify call is shown below:

rudderanalytics.identify('1hKOmRA4el9Zt1WSfVJIVo4GRlm', {
    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, the device having that playerId will be updated. The externalId is case-sensitive; for correct mapping, it should present in the exact format as seen above.

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-mentioned 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 browser, RudderStack checks the browser name in deviceTypeMapping as mentioned in the above code snippet 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.

It is recommended to send device.token for push notifications.

• For email and SMS, enable the Toggle on to add a device using email and Toggle on to add a device using phone number settings in the RudderStack dashboard and send the relevant data (email or phone) in the event payload.

Property mapping

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

All the string key-value pairs from traits are mapped inside the tags object as it is.

Track

You can use the track 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.

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: "Zara"
});

Property mapping

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

RudderStack maps all properties added in the Allowed Property List setting in the RudderStack dashboard 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('1hKOmRA4el9Zt1WSfVJIVo4GRlm', {
  name: "Apple Inc.",
  location: "USA",
});

Property mapping

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

RudderStack maps all properties added in the Allowed Property List setting in the RudderStack dashboard 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.

FAQ

Where can I find the OneSignal App ID?

To get your OneSignal App ID, follow these steps:

1. Log into your OneSignal dashboard.
2. Go to your app’s Settings > Keys & IDs.
3. You will find the OneSignal App ID:

Questions? Contact us by email or on Slack