feat(KNO-10408): Update docs around Channel Data Tokens + Devices

components/ui/MultiLangCodeBlock.tsx

@@ -43,6 +43,8 @@ const snippets = {
     .default,
   "users.setChannelData": require("../../data/code/users/set-channel-data")
     .default,
+  "users.setChannelDataDevices":
+    require("../../data/code/users/set-channel-data-devices").default,
   "users.setChannelData-push":
     require("../../data/code/users/set-channel-data-push").default,
   "users.setChannelData-one-signal":

content/integrations/push/apns.mdx

@@ -81,6 +81,9 @@ Overrides are merged into the notification payload sent to APNs. See the <a href
 
 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>.
 
-| Property | Type     | Description               |
-| -------- | -------- | ------------------------- |
-| tokens\* | string[] | One or more device tokens |
+Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
+
+| Property  | Type                                                                              | Description                                                   |
+| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| tokens\*  | `string[]`                                                                        | One or more device tokens. Required when not using `devices`. |
+| 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

@@ -305,6 +305,9 @@ See <a href="https://docs.aws.amazon.com/sns/latest/dg/sns-message-attributes.ht
 
 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.
 
-| Property      | Type     | Description                                                                                  |
-| ------------- | -------- | -------------------------------------------------------------------------------------------- |
-| target_arns\* | string[] | One or more platform endpoint ARNs associated with a platform application and a device token |
+Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
+
+| Property      | Type                                                                              | Description                                                                                                                      |
+| ------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| target_arns\* | `string[]`                                                                        | One or more platform endpoint ARNs associated with a platform application and a device token. Required when not using `devices`. |
+| 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

@@ -0,0 +1,97 @@
+---
+title: Push notification device metadata
+description: How to use channel data to store device-level metadata for push notifications.
+tags:
+  [
+    "push token",
+    "channel data",
+    "device token",
+    "device metadata",
+    "locale",
+    "timezone",
+  ]
+section: Integrations > Push
+layout: integrations
+---
+
+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).
+
+This feature is available for all push providers except OneSignal.
+
+## Availability
+
+| Provider   | Device metadata supported? |
+| ---------- | -------------------------- |
+| APNs       | ✅                         |
+| FCM        | ✅                         |
+| Expo       | ✅                         |
+| Amazon SNS | ✅                         |
+| OneSignal  | ❌                         |
+
+## How it works
+
+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.
+
+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:
+
+- The translation language used to render message content for the device will be according to the device-level `locale` property.
+- The timezone used to evaluate the send window for the device will be according to the device-level `timezone` property.
+
+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.
+
+<Callout
+  type="warning"
+  title="Note:"
+  text={
+    <>
+      If you're using Knock's Amazon SNS push notification integration, a{" "}
+      <code>target_arn</code> or <code>target_arns</code> will take the place of{" "}
+      <code>token</code> or <code>tokens</code> when setting channel data. Their
+      functionality is interchangeable. Reference the{" "}
+      <a href="/integrations/push/aws-sns">provider-specific documentation</a>{" "}
+      for more details.
+    </>
+  }
+/>
+
+### Setting device metadata
+
+In the example below, we're setting a user's device token by passing `devices` rather than `tokens`.
+
+<MultiLangCodeBlock
+  snippet="users.setChannelDataDevices"
+  title="Set push channel data for a user via devices"
+/>
+
+If you do not require device-level locale or timezone properties, you can simply set channel data by passing a list of `tokens` strings.
+
+<MultiLangCodeBlock
+  snippet="users.setChannelData"
+  title="Set push channel data for a user via tokens"
+/>
+
+### Getting push channel data
+
+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.
+
+```json title="Example push channel data response"
+{
+  "__typename": "ChannelData",
+  "channel_id": "123e4567-e89b-12d3-a456-426614174000",
+  "data": {
+    "devices": [
+      {
+        "locale": "en-US",
+        "timezone": "America/New_York",
+        "token": "user_device_token_1"
+      },
+      {
+        "locale": null,
+        "timezone": null,
+        "token": "user_device_token_2"
+      }
+    ],
+    "tokens": ["user_device_token_1", "user_device_token_2"]
+  }
+}
+```

content/integrations/push/expo.mdx

@@ -60,6 +60,9 @@ Overrides are merged into the notification payload sent to Expo. See the <a href
 
 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>.
 
-| Property | Type     | Description               |
-| -------- | -------- | ------------------------- |
-| tokens\* | string[] | One or more device tokens |
+Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
+
+| Property  | Type                                                                              | Description                                                   |
+| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| tokens\*  | `string[]`                                                                        | One or more device tokens. Required when not using `devices`. |
+| 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

@@ -142,8 +142,11 @@ The following are common FCM errors you may see in your message delivery logs:
 
 ## Channel data requirements
 
-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.
+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.
 
-| Property | Type     | Description               |
-| -------- | -------- | ------------------------- |
-| tokens\* | string[] | One or more device tokens |
+Alternatively, you can store a list of `devices` objects when using [device metadata](/integrations/push/device-metadata).
+
+| Property  | Type                                                                              | Description                                                   |
+| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| tokens\*  | `string[]`                                                                        | One or more device tokens. Required when not using `devices`. |
+| 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

@@ -12,7 +12,8 @@ Knock supports sending push notifications directly to native services such as Ap
 
 - **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!
 - **Cross-provider, single template**: you can send the same templated message across multiple providers to reduce the amount of templates to maintain.
-- **Token deregistration**: if a recipient's token(s) is invalid resulting in a `bounced` message when attempting to send, remove the token.
+- [**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.
+- [**Device metadata**](/integrations/push/device-metadata): set device-level `locale` and `timezone` properties for translations and send window evaluation with supported providers.
 
 ## Channel groups
 

content/integrations/push/token-deregistration.mdx

@@ -6,7 +6,7 @@ section: Integrations > Push
 layout: integrations
 ---
 
-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.
+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.
 
 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.
 

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

@@ -13,7 +13,7 @@ At Knock we call this concept <a href="/api-reference/recipients/channel_data">`
 
 - 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.
 - 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.
-  - 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.
+- 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.
 - 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.
 
 ## Setting channel data
@@ -134,27 +134,63 @@ Any previously set channel data can be cleared by issuing an `unsetChannelData`
 
 ## Provider data requirements
 
-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.
+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.
 
 ### Push channels
 
-<AccordionGroup>
-  <Accordion title ="APNs (Apple Push Notification Service)">
-    | Property | Type       | Description               |
-    | -------- | ---------- | ------------------------- |
-    | tokens\* | `string[]` | One or more device tokens |
+You can set push channel data by passing either:
+
+- A list of `tokens` (or `target_arns` for [Amazon SNS](/integrations/push/aws-sns)) strings
+- 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).
+
+#### The `PushDevice` object
+
+The `PushDevice` object is used to optionally set device-level metadata for a push channel. It contains the following properties:
 
+| Property     | Type     | Description                                                                                                                               |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| token\*      | `string` | The device token to send the push notification to. Required for providers other than Amazon SNS.                                          |
+| target_arn\* | `string` | The ARN of a platform endpoint associated with a platform application and a device token. Required for Amazon SNS.                        |
+| locale       | `string` | The [locale](/concepts/translations#supported-locales) of the device.                                                                     |
+| 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). |
+
+#### Provider-specific requirements
+
+<AccordionGroup>
+  <Accordion title ="APNs (Apple Push Notification service)">
+    You must provide one of `tokens` or `devices`.
+
+    | Property  | Type                                     | Description                 |
+    | --------- | ---------------------------------------- | --------------------------- |
+    | tokens\*  | `string[]`                               | One or more device tokens.  |
+    | devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
+
   </Accordion>
   <Accordion title ="FCM (Firebase Cloud Messaging)">
-    | Property | Type       | Description               |
-    | -------- | ---------- | ------------------------- |
-    | tokens\* | `string[]` | One or more device tokens |
+    You must provide one of `tokens` or `devices`.
+
+    | Property  | Type                                     | Description                 |
+    | --------- | ---------------------------------------- | --------------------------- |
+    | tokens\*  | `string[]`                               | One or more device tokens.  |
+    | devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
 
   </Accordion>
   <Accordion title ="Expo">
-    | Property | Type       | Description               |
-    | -------- | ---------- | ------------------------- |
-    | tokens\* | `string[]` | One or more device tokens |
+    You must provide one of `tokens` or `devices`.
+
+    | Property  | Type                                     | Description                 |
+    | --------- | ---------------------------------------- | --------------------------- |
+    | tokens\*  | `string[]`                               | One or more device tokens.  |
+    | devices\* | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects. |
+
+  </Accordion>
+  <Accordion title ="AWS SNS">
+    You must provide one of `target_arns` or `devices`.
+
+    | Property      | Type                                     | Description                     |
+    | ------------- | ---------------------------------------- | ------------------------------- |
+    | target_arns\* | `string[]`                               | One or more device target ARNs. |
+    | devices\*     | [`PushDevice[]`](#the-pushdevice-object) | One or more device objects.     |
 
   </Accordion>
   <Accordion title ="OneSignal">