How to send push notifications using OneSignal
In this guide we'll walk through how to configure a OneSignal provider in Knock to send push notifications. This guide assumes that you've already created a OneSignal channel in the Knock dashboard.
Your OneSignal channel expects that you are using Knock to author Push notification templates. Those templates are then passed to OneSignal as content.
How to configure OneSignal Push with Knock
To set up OneSignal Push with Knock you will need:
- Your OneSignal App ID
- Your OneSignal API Key for sending notifications
- To select a mode of operation between using
external_ids(recommended) orplayer_ids(deprecated by OneSignal).
Using OneSignal Push with Knock
Using external_id (recommended)
If you’re using an External ID to reference your OneSignal users within Knock, you do not need to supply any additional data to initiate a request. We will automatically pass your Knock user ID to OneSignal as the external_id.
Using player_id
When using Player IDs you will need to store the player_id for a user within Knock as ChannelData for the OneSignal Push channel. This ensures that Knock has the correct value to pass to send a notification to a recipient when a workflow is triggered.
You can retrieve the player_id from OneSignal once a user has been registered, either by using the OneSignal mobile SDK, or by using a webhook from OneSignal.
Data passed to OneSignal
When sending a push notification to OneSignal, we will automatically pass the following into the attachments data:
| Property | Type | Description |
|---|---|---|
| knock_message_id* | string | The message ID of the corresponding Knock message |
| data * | string | Any key/value data passed through in your trigger call |
Silent/background notifications
When selecting to send as a silent/background notification, Knock will passthrough the content_available=true option to OneSignal. You can enable this per push notification template by clicking "Manage template settings" in the header of the template editor.
Using overrides to customize notifications
We have full support for overriding the payload sent to OneSignal for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Manage template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting data properties and referencing attributes on your recipients.
Overrides are merged into the notification payload sent to OneSignal. See the OneSignal documentation for more details. Knock uses the "Aliases" targeting strategy to send push notifications to specific users via External ID.
Managing tokens
By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.
When using player_id mode, Knock provides an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. This feature is not available when using external_id mode since Knock doesn't directly manage any tokens in this case.
You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our token deregistration guide for more details.
Channel data requirements
When your OneSignal push channel is configured to use player_ids you must supply ChannelData per-recipient that contains one or more player_ids for a user.