How to send push notifications to Apple Push Notifications service
In this guide we'll walk through how to configure an Apple Push Notifications service (APNS) provider in Knock to send iOS push notifications. This guide assumes that you've already created an APNS channel in the Knock dashboard.
How to configure Apple Push Notifications service with Knock
There are two ways to configure APNS with Knock. You can use a token-based authentication scheme or a certificate-based authentication scheme. Depending on which you choose, you'll need to get different information from Xcode and your Apple developer account.
Token-based authentication configuration
Note: Knock recommends token-based authentication for all APNS channel connections.
You can read about how to setup a token connection to APNS in the documentation. For your Knock channel configuration, you will need:
- A provider token signing key (a private key)
- The key identifier (a 10 digit identifier from your Apple developer account)
- The team identifier (a 10 digit identifier from your Apple developer account)
Certificate-based authentication configuration
You can read aout how to setup a certificate connection to APNS in the documentation. For your Knock channel configuration, you will need:
- A provider certificate (from your Apple developer account)
- A private key (generated in the process above)
Both of these values should be converted according to the instructions here prior to providing them to your Knock channel configuration.
Using APNS with Knock
In order to use APNS with Knock you'll need to synchronize your users device tokens retrieved from the APNS SDK to Knock by setting channel data for your recipient.
You can follow the quickstart guide on APNS to see how to get the device token.
Managing tokens
Knock makes no assumptions about managing your device tokens for you. Meaning if a recipient opts-out of receiving notifications on a device, or the token expires, it is up to you to remove the token from the recipients channel data. This behavior is subject to change in the future.
Data passed to APNS
When sending a notification to APNS, we also pass through the following attributes:
| 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
We support sending APNS notifications as "silent", data-only notifications within Knock. You can enable this per push notification template under the 3-dot menu in the header of the template editor.
When silent push is enabled, we'll no longer pass through the content payload and your message will be sent with the content-available: 1 flag as expected by APNS. All properties in the data payload described above will be sent with your notification.
Using overrides to customize notifications
We have full support for overriding the payload sent to APNS for adding things like badge counts, extra data properties, and sound files. You can set the push overrides on the template settings modal, open it by clicking on the "Manage template settings" button. Push overrides support liquid for injecting data properties and referencing attributes on your recipients.
See the APNS documentation for details.
| Property | Type | Description |
|---|---|---|
| headers | dictionary | APNS specific headers (apns-priority, apns-expiration, apns-push-type, apns-topic, apns-collapse-id) |
| aps | dictionary | Overrides to send to the push payload (sound, alert, badge, thread-id) |
| any | any | Any other key values to send as part of the push message |
Channel data requirements
In order to use a configured APNS channel you must store a list of one or more device tokens for the user or the object that you wish to deliver a notification to. You can retrieve a device token by following the guide on the Apple developer documentation.
| Property | Type | Description |
|---|---|---|
| tokens* | string[] | One or more device tokens |