Skip to content

Commit 684e72e

Browse files
andy-knockcellomatt
andy-knock
and
cellomatt
authored
feat(KNO-10408): Update docs around Channel Data Tokens + Devices (#1202)
* a * a * a * a * a * chore: update device metadata docs * chore: additional updates and formatting * format * chore: update example response to match code example * address feedback * small edit for clarity --------- Co-authored-by: Matt Kufchak <matt@knock.app>
1 parent f778444 commit 684e72e

File tree

12 files changed

+348
-29
lines changed

12 files changed

+348
-29
lines changed

‎components/ui/MultiLangCodeBlock.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ const snippets = {
4343
.default,
4444
"users.setChannelData": require("../../data/code/users/set-channel-data")
4545
.default,
46+
"users.setChannelDataDevices":
47+
require("../../data/code/users/set-channel-data-devices").default,
4648
"users.setChannelData-push":
4749
require("../../data/code/users/set-channel-data-push").default,
4850
"users.setChannelData-one-signal":

‎content/integrations/push/apns.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,9 @@ Overrides are merged into the notification payload sent to APNs. See the <a href
8181

8282
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 tutorial in the <a href="https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns" target="_blank">Apple developer documentation</a>.
8383

84-
| Property | Type | Description |
85-
| -------- | -------- | ------------------------- |
86-
| tokens\* | string[] | One or more device tokens |
84+
Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
85+
86+
| Property | Type | Description |
87+
| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
88+
| tokens\* | `string[]` | One or more device tokens. Required when not using `devices`. |
89+
| devices\* | [`PushDevice[]`](/managing-recipients/setting-channel-data#the-pushdevice-object) | One or more device objects. Required when not using `tokens`. |

‎content/integrations/push/aws-sns.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,9 @@ See <a href="https://docs.aws.amazon.com/sns/latest/dg/sns-message-attributes.ht
305305

306306
In order to use a configured Amazon SNS channel, you must store a list of one or more platform endpoint ARNs for the user or the object that you wish to deliver a notification to. See <a href="https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html" target="_blank">Setting up an Amazon SNS platform endpoint for mobile notifications</a> for more details on creating platform endpoints.
307307

308-
| Property | Type | Description |
309-
| ------------- | -------- | -------------------------------------------------------------------------------------------- |
310-
| target_arns\* | string[] | One or more platform endpoint ARNs associated with a platform application and a device token |
308+
Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
309+
310+
| Property | Type | Description |
311+
| ------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
312+
| target_arns\* | `string[]` | One or more platform endpoint ARNs associated with a platform application and a device token. Required when not using `devices`. |
313+
| devices\* | [`PushDevice[]`](/managing-recipients/setting-channel-data#the-pushdevice-object) | One or more device objects. Required when not using `target_arns`. |

‎content/integrations/push/device-metadata.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Push notification device metadata
3+
description: How to use channel data to store device-level metadata for push notifications.
4+
tags:
5+
[
6+
"push token",
7+
"channel data",
8+
"device token",
9+
"device metadata",
10+
"locale",
11+
"timezone",
12+
]
13+
section: Integrations > Push
14+
layout: integrations
15+
---
16+
17+
When [setting channel data for push channels](/managing-recipients/setting-channel-data#push-channels), Knock provides the option to set additional metadata alongside a device token. When set, a device-level `locale` will be used when [translating](/concepts/translations) message content for the device, and the `timezone` will be used to evalute [send windows](/designing-workflows/send-windows).
18+
19+
This feature is available for all push providers except OneSignal.
20+
21+
## Availability
22+
23+
| Provider | Device metadata supported? |
24+
| ---------- | -------------------------- |
25+
| APNs | ✅ |
26+
| FCM | ✅ |
27+
| Expo | ✅ |
28+
| Amazon SNS | ✅ |
29+
| OneSignal | ❌ |
30+
31+
## How it works
32+
33+
When setting a recipient's channel data for a supported push channel, you can pass a list of `devices` objects (containing `token`, `locale`, and `timezone`) rather than a list of `tokens` strings.
34+
35+
When a workflow includes a push channel step and the `recipient` channel data includes device metadata, any device-level values will take precedence over the recipient-level `locale` and `timezone` [properties](/managing-recipients/identifying-recipients#reserved-properties). This means:
36+
37+
- The translation language used to render message content for the device will be according to the device-level `locale` property.
38+
- The timezone used to evaluate the send window for the device will be according to the device-level `timezone` property.
39+
40+
All other features of push channels (including [token deregistration](/integrations/push/token-deregistration)) will function the same way, regardless of whether device metadata is set.
41+
42+
<Callout
43+
type="warning"
44+
title="Note:"
45+
text={
46+
<>
47+
If you're using Knock's Amazon SNS push notification integration, a{" "}
48+
<code>target_arn</code> or <code>target_arns</code> will take the place of{" "}
49+
<code>token</code> or <code>tokens</code> when setting channel data. Their
50+
functionality is interchangeable. Reference the{" "}
51+
<a href="/integrations/push/aws-sns">provider-specific documentation</a>{" "}
52+
for more details.
53+
</>
54+
}
55+
/>
56+
57+
### Setting device metadata
58+
59+
In the example below, we're setting a user's device token by passing `devices` rather than `tokens`.
60+
61+
<MultiLangCodeBlock
62+
snippet="users.setChannelDataDevices"
63+
title="Set push channel data for a user via devices"
64+
/>
65+
66+
If you do not require device-level locale or timezone properties, you can simply set channel data by passing a list of `tokens` strings.
67+
68+
<MultiLangCodeBlock
69+
snippet="users.setChannelData"
70+
title="Set push channel data for a user via tokens"
71+
/>
72+
73+
### Getting push channel data
74+
75+
Regardless of whether you set `tokens` or `devices`, you'll see them returned in both formats when retrieving channel data. Devices will include `null` values for the `locale` and `timezone` properties if they were not provided when channel data was set.
76+
77+
```json title="Example push channel data response"
78+
{
79+
"__typename": "ChannelData",
80+
"channel_id": "123e4567-e89b-12d3-a456-426614174000",
81+
"data": {
82+
"devices": [
83+
{
84+
"locale": "en-US",
85+
"timezone": "America/New_York",
86+
"token": "user_device_token_1"
87+
},
88+
{
89+
"locale": null,
90+
"timezone": null,
91+
"token": "user_device_token_2"
92+
}
93+
],
94+
"tokens": ["user_device_token_1", "user_device_token_2"]
95+
}
96+
}
97+
```

‎content/integrations/push/expo.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ Overrides are merged into the notification payload sent to Expo. See the <a href
6060

6161
In order to use a configured Expo 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 tutorial in the <a href="https://docs.expo.dev/push-notifications/push-notifications-setup/" target="_blank">Expo developer documentation</a>.
6262

63-
| Property | Type | Description |
64-
| -------- | -------- | ------------------------- |
65-
| tokens\* | string[] | One or more device tokens |
63+
Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
64+
65+
| Property | Type | Description |
66+
| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
67+
| tokens\* | `string[]` | One or more device tokens. Required when not using `devices`. |
68+
| devices\* | [`PushDevice[]`](/managing-recipients/setting-channel-data#the-pushdevice-object) | One or more device objects. Required when not using `tokens`. |

‎content/integrations/push/firebase.mdx‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,11 @@ The following are common FCM errors you may see in your message delivery logs:
142142

143143
## Channel data requirements
144144

145-
In order to use a configured FCM 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. If you use multiple device tokens for a single user or object, Knock will generate and try and deliver a notification for each unique token.
145+
In order to use a configured FCM 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. If you use multiple device tokens for a single user or object, Knock will generate and try to deliver a notification for each unique token.
146146

147-
| Property | Type | Description |
148-
| -------- | -------- | ------------------------- |
149-
| tokens\* | string[] | One or more device tokens |
147+
Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
148+
149+
| Property | Type | Description |
150+
| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
151+
| tokens\* | `string[]` | One or more device tokens. Required when not using `devices`. |
152+
| devices\* | [`PushDevice[]`](/managing-recipients/setting-channel-data#the-pushdevice-object) | One or more device objects. Required when not using `tokens`. |

‎content/integrations/push/overview.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Knock supports sending push notifications directly to native services such as Ap
1212

1313
- **No stateful connections to manage**: we take care of all of the complexity of managing and maintaining stateful connections to your push providers, just simply send us notifications and we'll get them delivered!
1414
- **Cross-provider, single template**: you can send the same templated message across multiple providers to reduce the amount of templates to maintain.
15-
- **Token deregistration**: if a recipient's token(s) is invalid resulting in a `bounced` message when attempting to send, remove the token.
15+
- [**Token deregistration**](/integrations/push/token-deregistration): if a recipient's invalid device token results in a `bounced` message when attempting to send, Knock can optionally remove the token.
16+
- [**Device metadata**](/integrations/push/device-metadata): set device-level `locale` and `timezone` properties for translations and send window evaluation with supported providers.
1617

1718
## Channel groups
1819

‎content/integrations/push/token-deregistration.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ section: Integrations > Push
66
layout: integrations
77
---
88

9-
For push providers only, Knock provides an opt-in, provider-agnostic token management capability known as token deregistration. Knock removes invalid tokens from a recipient's corresponding channel data if that token results in a `bounced` message on send.
9+
For push providers only, Knock provides an opt-in, provider-agnostic token management capability known as token deregistration. Knock removes invalid tokens (and devices, when using [device metadata](/integrations/push/device-metadata)) from a recipient's corresponding channel data if that token results in a `bounced` message on send.
1010

1111
This feature is available for all push providers, except OneSignal when the recipient mode is set to `external_id`. In this case, Knock only has access to the user's ID and therefore cannot deregister the associated external token.
1212

‎content/managing-recipients/setting-channel-data.mdx‎

Lines changed: 49 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ At Knock we call this concept <a href="/api-reference/recipients/channel_data">`
1313

1414
- For channel types that require channel data (such as [push](/integrations/push/overview) channels and [chat](/integrations/chat/overview) channels like Slack), the channel step will be skipped during a workflow run if the required `channel_data` is not stored on the recipient.
1515
- Knock stores channel data for you but makes no assumptions about whether the stored channel data is valid. That means that if a push token expires, it's your responsibility to omit/update that token for future notifications.
16-
- For push providers, Knock offers an opt-in [token deregistration](/integrations/push/token-deregistration) feature that automatically removes invalid tokens from a recipient's channel data when messages bounce.
16+
- For push providers, Knock offers an opt-in [token deregistration](/integrations/push/token-deregistration) feature that automatically removes invalid tokens from a recipient's channel data when messages bounce.
1717
- Setting channel data always requires a `channel_id`, which can be obtained in the Dashboard under the **Channels and sources** page in your account settings. A channel ID is always a UUID v4.
1818

1919
## Setting channel data
@@ -134,27 +134,63 @@ Any previously set channel data can be cleared by issuing an `unsetChannelData`
134134

135135
## Provider data requirements
136136

137-
Channel data requirements for each provider are listed below. Typically `channel_data` comprises a `token` or other value that is used to uniquely identify a user's device.
137+
Channel data requirements for each channel type and provider are listed below. Typically `channel_data` comprises a `token` or other value that is used to uniquely identify a user's device.
138138

139139
### Push channels
140140

141-
<AccordionGroup>
142-
<Accordion title ="APNs (Apple Push Notification Service)">
143-
| Property | Type | Description |
144-
| -------- | ---------- | ------------------------- |
145-
| tokens\* | `string[]` | One or more device tokens |
141+
You can set push channel data by passing either:
142+
143+
- A list of `tokens` (or `target_arns` for [Amazon SNS](/integrations/push/aws-sns)) strings
144+
- A list of `devices` objects for supported push providers. If set, this [device-level metadata](/integrations/push/device-metadata) will be used when evaluating [translations](/concepts/translations) and [send windows](/designing-workflows/send-windows).
145+
146+
#### The `PushDevice` object
147+
148+
The `PushDevice` object is used to optionally set device-level metadata for a push channel. It contains the following properties:
146149

150+
| Property | Type | Description |
151+
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
152+
| token\* | `string` | The device token to send the push notification to. Required for providers other than Amazon SNS. |
153+
| target_arn\* | `string` | The ARN of a platform endpoint associated with a platform application and a device token. Required for Amazon SNS. |
154+
| locale | `string` | The [locale](/concepts/translations#supported-locales) of the device. |
155+
| timezone | `string` | The timezone of the device. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
156+
157+
#### Provider-specific requirements
158+
159+
<AccordionGroup>
160+
<Accordion title ="APNs (Apple Push Notification service)">
161+
You must provide one of `tokens` or `devices`.
162+
163+
| Property | Type | Description |
164+
| --------- | ---------------------------------------- | --------------------------- |
165+
| tokens\* | `string[]` | One or more device tokens. |
166+
| devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
167+
147168
</Accordion>
148169
<Accordion title ="FCM (Firebase Cloud Messaging)">
149-
| Property | Type | Description |
150-
| -------- | ---------- | ------------------------- |
151-
| tokens\* | `string[]` | One or more device tokens |
170+
You must provide one of `tokens` or `devices`.
171+
172+
| Property | Type | Description |
173+
| --------- | ---------------------------------------- | --------------------------- |
174+
| tokens\* | `string[]` | One or more device tokens. |
175+
| devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
152176

153177
</Accordion>
154178
<Accordion title ="Expo">
155-
| Property | Type | Description |
156-
| -------- | ---------- | ------------------------- |
157-
| tokens\* | `string[]` | One or more device tokens |
179+
You must provide one of `tokens` or `devices`.
180+
181+
| Property | Type | Description |
182+
| --------- | ---------------------------------------- | --------------------------- |
183+
| tokens\* | `string[]` | One or more device tokens. |
184+
| devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
185+
186+
</Accordion>
187+
<Accordion title ="AWS SNS">
188+
You must provide one of `target_arns` or `devices`.
189+
190+
| Property | Type | Description |
191+
| ------------- | ---------------------------------------- | ------------------------------- |
192+
| target_arns\* | `string[]` | One or more device target ARNs. |
193+
| devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
158194

159195
</Accordion>
160196
<Accordion title ="OneSignal">

0 commit comments

Comments
 (0)