# Send Events to OneSignal (Device Model)

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](https://github.com/rudderlabs/rudder-transformer/tree/main/src/v0/destinations/one_signal).

{{< danger >}}
OneSignal device model is deprecated. RudderStack recommends sending events to OneSignal via their [User Model API]({{< ref "destinations/streaming-destinations/onesignal/user-model.md" >}}).

See the [OneSignal documentation](https://documentation.onesignal.com/docs/user-model-migration-guide) for more information.
{{< /danger >}}

## Identify 

You can make an [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call to [add a new device](https://documentation.onesignal.com/reference/add-a-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: 

```javascript
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.
{{< /info >}}

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

```javascript
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:

```javascript
"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 property | OneSignal property |
| :-------| :--------| 
| `context.device.model`  | `device_model` | 
| `context.os.version` | `device_os` | 
| `context.timezone` | `timezone` | 
| `userId` | `external_user_id` | 
| `context.locale` | `language` |
| `traits.createdAt` <br />`context.traits.createdAt`<br />`timestamp`<br />`originalTimestamp` | `created_at` <br /> `last_active` | 
| `traits.country`<br />`context.traits.country`<br />`traits.address.country`<br />`context.traits.address.country` | `country` | 
| `integrations.one_signal.deviceType` | `device_type` | 
| `integrations.one_signal.identifier` | `identifier` |

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.
{{< /info >}}

## Track

You can use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) 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`](#identify) call.
{{< /info >}}

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:

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

### Property mapping

RudderStack maps the following properties to the corresponding OneSignal properties:

| RudderStack property | OneSignal property |
| :-------| :--------| 
| `userId` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `external_user_id` | 

{{< info >}}
RudderStack maps all properties added in the **Allowed Property List** [dashboard setting]({{< ref "destinations/streaming-destinations/onesignal/setup-guide.md#connection-settings" >}}) 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.
{{< /info >}}

## Group

You can use the [`group`]({{< ref "event-spec/standard-events/group.md" >}}) call to group the devices with the device tags having the same `groupId`.

A sample `group` call is as shown:

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

### Property mapping

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

| RudderStack property | OneSignal property | Presence | 
| :-------| :--------| :------|
| `groupId` | `groupId` | Required | 

{{< info >}}
RudderStack maps all properties added in the **Allowed Property List** [dashboard setting]({{< ref "destinations/streaming-destinations/onesignal/setup-guide.md#connection-settings" >}}) 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.
{{< /info >}}