From 1612f66232a05e6ab72d01538b6446549d4c111c Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Fri, 8 Dec 2023 10:12:59 -0500 Subject: [PATCH] feat: add in-app feed response filter docs (#349) * feat: add in-app feed response filter docs * chore: run formatter * fix: formatting glitch --- .github/pull_request_template.md | 5 + content/cli.mdx | 4 +- content/concepts/schedules.mdx | 29 ++-- content/getting-started/knock-and-postman.md | 2 +- content/guides/building-recurring-digests.mdx | 1 - content/guides/customer-webhooks.mdx | 34 ++-- content/in-app-ui/angular/overview.mdx | 2 +- content/integrations/in-app/knock.mdx | 53 ++++++ .../manage-your-account/data-obfuscation.mdx | 11 +- content/mapi.mdx | 164 +++++++++--------- content/reference.mdx | 6 +- .../send-notifications/message-statuses.mdx | 19 +- package.json | 2 +- 13 files changed, 192 insertions(+), 140 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3a9cde6c..cf77ba2a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,13 +1,18 @@ ### Description + ** Describe what, why and how of the changes clearly and concisely. Add any additional useful context or info, as necessary. ** ### Todos + ** List any todo items necessary before merging, if any. Delete if none. ** + - [ ] Sample todo item 1 - [ ] Sample todo item 2 ### Tasks + ** Link to task(s) which this PR corresponds to. Example: [KNO-54](https://linear.app/knock/issue/KNO-54/create-a-pr-template) ** ### Screenshots + ** Attach any screenshots or recordings to visually illustrate the changes, as necessary. Delete if not relevant. ** diff --git a/content/cli.mdx b/content/cli.mdx index 3d95057c..d5f72402 100644 --- a/content/cli.mdx +++ b/content/cli.mdx @@ -939,7 +939,7 @@ List all commits in the environment. Use an `--environment` flag to specify the type="string" description="The environment to use. Defaults to development." /> - - - Note: executing schedules in recipient timezones is currently only supported by recurring schedules. + Note: executing schedules in recipient + timezones is currently only supported by{" "} + recurring schedules. } /> diff --git a/content/getting-started/knock-and-postman.md b/content/getting-started/knock-and-postman.md index ea1df9e2..4deb804d 100644 --- a/content/getting-started/knock-and-postman.md +++ b/content/getting-started/knock-and-postman.md @@ -13,7 +13,7 @@ In this guide you'll fork the Knock collection into your Postman workspace and c 1. Install [Postman](https://www.postman.com/downloads/) if you don't have it already. 2. [Fork the Knock API Postman collection](https://god.gw.postman.com/run-collection/10721026-cd261902-9249-4714-b7d3-896c15987fa5?action=collection%2Ffork&collection-url=entityId%3D10721026-cd261902-9249-4714-b7d3-896c15987fa5%26entityType%3Dcollection%26workspaceId%3De0ad9a88-e3dd-462b-8c44-695c9c10b8e5#?env%5BKnock%20environment%20template%5D=W3sia2V5IjoiYmFzZV91cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vYXBpLmtub2NrLmFwcCIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic2VjcmV0X2tleSIsInZhbHVlIjoic2tfdGVzdF94eHh4IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaWNfa2V5IiwidmFsdWUiOiJwa190ZXN0X3h4eHgiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6IndvcmtmbG93X2tleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJyZWNpcGllbnRfdXNlcl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhY3Rvcl91c2VyX2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImZlZWRfaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidXNlcl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ1c2VyX25hbWUiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidXNlcl9lbWFpbCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ1c2VyX2F2YXRhcl91cmwiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicHJlZmVyZW5jZV9zZXRfaWQiLCJ2YWx1ZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=). We recommend forking the collection (as opposed to creating a copy) so that you can pull changes we make to the source collection. - * We provide a separate [Management API Postman collection](https://www.postman.com/knock-labs/workspace/knock-public-workspace/collection/15616728-9ed6000c-13bc-43f5-a2cf-db6daea256bd?action=share&creator=15616728&active-environment=15616728-6df39335-c6f9-4c9d-99d5-73e3c7ffe524). You can use use this to test our [Management API](https://docs.knock.app/mapi#overview). + - We provide a separate [Management API Postman collection](https://www.postman.com/knock-labs/workspace/knock-public-workspace/collection/15616728-9ed6000c-13bc-43f5-a2cf-db6daea256bd?action=share&creator=15616728&active-environment=15616728-6df39335-c6f9-4c9d-99d5-73e3c7ffe524). You can use use this to test our [Management API](https://docs.knock.app/mapi#overview). ## Configure your Knock environments in Postman diff --git a/content/guides/building-recurring-digests.mdx b/content/guides/building-recurring-digests.mdx index b752f2e0..1bdbe7e9 100644 --- a/content/guides/building-recurring-digests.mdx +++ b/content/guides/building-recurring-digests.mdx @@ -104,7 +104,6 @@ There are new notifications waiting for you to review. Please go into the app to Note: you'll need to configure an email channel via a provider in order to start sending emails with Knock. You can read more on{" "} configuring email channels here - . } /> diff --git a/content/guides/customer-webhooks.mdx b/content/guides/customer-webhooks.mdx index 62ec91d4..fdcfccbd 100644 --- a/content/guides/customer-webhooks.mdx +++ b/content/guides/customer-webhooks.mdx @@ -1,5 +1,5 @@ --- -title: Building customer-facing, configurable webhooks with Knock +title: Building customer-facing, configurable webhooks with Knock description: Learn how to use Knock to send per-customer configurable webhooks as part of your notification workflows. tags: ["webhooks", "webhooks as a service"] section: Guides @@ -18,7 +18,7 @@ In Knock, we’ll model this as follows: First we’ll upsert the project as an object in Knock. We’re putting the project under a `projects` collection. -```js Upsert our project object +```js Upsert our project object const project = await knock.objects.set("projects", "project-1", { name: "My project", }); @@ -33,7 +33,7 @@ const webhookId = "some-unique-id"; // Create the webhook object with the configuration const projectWebhook = await knock.objects.set("project_webhooks", webhookId, { events: ["project:created"], - url: "https://some-url.com/incoming/webhook", + url: "https://some-url.com/incoming/webhook", }); // Associate the webhook with the project @@ -46,14 +46,14 @@ If at any point we need to list all of the configured webhooks for a given proje ```js List webhooks for a given project const { entries: webhookSubscriptions } = await knock.objects.listSubscriptions( - "projects", - "project-1" + "projects", + "project-1", ); ``` ## Configuring an HTTP channel -Now we’re going to configure our Webhook HTTP channel in Knock. You can learn how to configure a Webhook HTTP channel in our [webhook channel overview](/integrations/webhook/overview). +Now we’re going to configure our Webhook HTTP channel in Knock. You can learn how to configure a Webhook HTTP channel in our [webhook channel overview](/integrations/webhook/overview). Next, we’ll configure the webhook request for our new webhook channel. For the channel URL we’re going to configure it as `{{ recipient.url }}` which tells Knock to use the URL configured on the webhook recipient object: @@ -66,7 +66,7 @@ And for the body of the payload that we send per webhook event, we’ll use the "type": "{{ event_type }}", "data": {{ payload }}, "created_at": {{ timestamp }} -} +} ``` ## Building your webhook notification workflow @@ -85,17 +85,15 @@ We don’t need to customize any of the data sent in the webhook channel, so we ## Triggering your webhook notification workflow -Now our workflow is configured, we can trigger it via the API. We’ll pass the `project` as a recipient to the workflow, which will automatically trigger our workflow to execute *for all webhooks configured*. +Now our workflow is configured, we can trigger it via the API. We’ll pass the `project` as a recipient to the workflow, which will automatically trigger our workflow to execute _for all webhooks configured_. ```js Trigger workflow for our project await knock.workflows.trigger("workflow-with-webhook-step", { - data: { - event_type: eventType, - payload: eventPayloadData, - }, - recipients: [ - { collection: "projects", id: "project-1" } - ], + data: { + event_type: eventType, + payload: eventPayloadData, + }, + recipients: [{ collection: "projects", id: "project-1" }], }); ``` @@ -114,10 +112,10 @@ You might want to provide a way to notify your customers that their webhooks are ## Frequently asked questions **How do I power different types of webhook events, should those be different notification workflows or a single workflow?** -The answer here really depends on how different the notifications around each event type need to be. You should consider structuring each event type as a different workflow if the types of notifications sent in each event type differ a lot, or if the templates between event types are sufficiently different. +The answer here really depends on how different the notifications around each event type need to be. You should consider structuring each event type as a different workflow if the types of notifications sent in each event type differ a lot, or if the templates between event types are sufficiently different. **How do I conditionally send to only to webhook objects?** -If you need to limit the execution of the workflow steps you can add a trigger condition onto your webhook channel steps that will only send to: +If you need to limit the execution of the workflow steps you can add a trigger condition onto your webhook channel steps that will only send to: - `recipient.__typename` is equal to `Object` - `recipient.collection` is equal to `project_webhooks` @@ -125,4 +123,4 @@ If you need to limit the execution of the workflow steps you can add a trigger c **How do I conditionally allow certain event types on my webhooks?** You can store an `event_types` property on your webhook object and use a trigger condition to express whether or not the step should be executed (as an allow list). -- `recipient.event_types` contains `some:event` \ No newline at end of file +- `recipient.event_types` contains `some:event` diff --git a/content/in-app-ui/angular/overview.mdx b/content/in-app-ui/angular/overview.mdx index 7d2ff3ca..43e897d7 100644 --- a/content/in-app-ui/angular/overview.mdx +++ b/content/in-app-ui/angular/overview.mdx @@ -4,7 +4,7 @@ description: Learn more about the in-app notifications experiences you can build section: Building in-app UI --- -Today we do not have Knock-built, out-of-the-box Angular components for in-app notifications UI. +Today we do not have Knock-built, out-of-the-box Angular components for in-app notifications UI. Our Knock community built this [Angular in-app feed example](https://github.com/knocklabs/angular-in-app-feed-example) you can use to get started with an Angular in-app feed in your own application. diff --git a/content/integrations/in-app/knock.mdx b/content/integrations/in-app/knock.mdx index 1d411945..f39c59f9 100644 --- a/content/integrations/in-app/knock.mdx +++ b/content/integrations/in-app/knock.mdx @@ -38,3 +38,56 @@ Note that the functionality above is just the default for what we've provided in Sometimes a user wants to remove a notification from their feed altogether. This is where notification archiving comes in. When a notification is archived, it is removed from the feed and is no longer visible to the end user. In the Knock in-app feed, a message can be archived by clicking the "x" in the top-right corner of a given notification. The in-app feed component doesn't give users a way to see their archived notifications out-of-the-box, but if you'd like to incorporate this into your own in-app feed you can use the `archived: only` parameter on the [GET feed request](/reference#get-feed). + +## Customizing API response content + +By default, the [in-app feed API](/reference#get-feed) will return: + +- One or more actors associated with each in-app notification (when set), including all custom properties under each actor +- All of the public variables (note: secret variables are never returned) +- The entire workflow trigger data associated with each in-app notification +- The recipient associated with each notification, including all custom properties set + +In some situations, you may need control over exactly what the in-app feed API returns. This is where our API response filter can be used to completely customize the keys returned for the entities in your in-app feed responses. + +| Property | Description | +| --------- | ------------------------------------------------------------------------------ | +| vars | Apply a filter to the environment variables returned | +| actor | Apply a filter to all actors returned from the feed endpoint | +| recipient | Apply a filter to the recipient returned from the feed endpoint | +| data | Apply a filter to workflow trigger data returned from the in-app feed endpoint | + +Each property accepts the following: + +- A boolean to indicate whether this entity should be omitted or included, entirely (defaults to `true`). +- An object with either `except` or `only` key paths for keys to exclude or include. Note: a nested keypath can be given using a `.`. + +### Example: customizing the actor data + +As an example, if you want to customize the properties returned under an actor to only include `id`, `name`, and `avatar` you can set a response filter such as: + +```json +{ + "actor": { + "only": ["id", "name", "avatar"] + } +} +``` + +If you want to omit certain keys from the actor you can use the `except` keyword: + +```json +{ + "actor": { + "except": ["email", "phone_number", "credit_card.last4"] + } +} +``` + +Or, if you want to exclude the actor from rendering you can set: + +```json +{ + "actor": false +} +``` diff --git a/content/manage-your-account/data-obfuscation.mdx b/content/manage-your-account/data-obfuscation.mdx index f008b1bc..6add0e49 100644 --- a/content/manage-your-account/data-obfuscation.mdx +++ b/content/manage-your-account/data-obfuscation.mdx @@ -5,15 +5,16 @@ tags: ["privacy", "data controls", "security", "privacy controls"] section: Manage your account --- -Enable customer data obfuscation on a per-environment basis to determine what data your team members can see in the Knock dashboard. +Enable customer data obfuscation on a per-environment basis to determine what data your team members can see in the Knock dashboard. ## Overview -When you choose Knock to power your notifications, you're also choosing to trust us with your customer data and the data you pass in your notifications. This is why [security](/security) is a foundational priority for us at Knock, and it's also why we built our customer data obfuscation controls. -With customer data obfuscation controls, the Knock dashboard automatically hides any data that might contain either user PII or customer proprietary data. This means that the only data your team members will see in the Knock dashboard is anonymous data such as UUIDs. Customer data obfuscation is managed via our backend, so users won't be able to get at this data through their browser consoles. +When you choose Knock to power your notifications, you're also choosing to trust us with your customer data and the data you pass in your notifications. This is why [security](/security) is a foundational priority for us at Knock, and it's also why we built our customer data obfuscation controls. -Customer data obfuscation is enabled on a [per-environment](/send-and-manage-data/environments) basis. This means you can obfuscate your customer data in your production environment, while still retaining access to your internal data in development environments for easy testing and debugging. +With customer data obfuscation controls, the Knock dashboard automatically hides any data that might contain either user PII or customer proprietary data. This means that the only data your team members will see in the Knock dashboard is anonymous data such as UUIDs. Customer data obfuscation is managed via our backend, so users won't be able to get at this data through their browser consoles. + +Customer data obfuscation is enabled on a [per-environment](/send-and-manage-data/environments) basis. This means you can obfuscate your customer data in your production environment, while still retaining access to your internal data in development environments for easy testing and debugging. ![A preview of customer data obfuscation enabled](/images/manage-your-account/customer-data-obfuscation.png) -To enable customer data obfuscation, go to the Knock dashboard > Settings > Environments. Select the "..." for the environment you'd like to configure and click "Edit environment." \ No newline at end of file +To enable customer data obfuscation, go to the Knock dashboard > Settings > Environments. Select the "..." for the environment you'd like to configure and click "Edit environment." diff --git a/content/mapi.mdx b/content/mapi.mdx index 0f59f53e..1dca32d3 100644 --- a/content/mapi.mdx +++ b/content/mapi.mdx @@ -1999,7 +1999,7 @@ You can retrieve all commits in a given environment, or show the details of one path="/commits/promote" withLink /> - - - - - + /> - + + ### Path parameters - + ### Returns @@ -2217,18 +2213,18 @@ A complete commit. ```json Response { - "id": "ce3e5457-34f2-4f53-94a2-2f316528d83f", - "resource" :{ - "identifier": "default", - "type": "email_layout" - }, - "author": { - "email": "John@gmail.com", - "name": "John Doe" - }, - "commit_message": "Initial email layout", - "environment": "development", - "created_at": "2023-09-22T18:57:21.704602Z" + "id": "ce3e5457-34f2-4f53-94a2-2f316528d83f", + "resource": { + "identifier": "default", + "type": "email_layout" + }, + "author": { + "email": "John@gmail.com", + "name": "John Doe" + }, + "commit_message": "Initial email layout", + "environment": "development", + "created_at": "2023-09-22T18:57:21.704602Z" } ``` @@ -2328,7 +2324,7 @@ Promotes one change to the subsequent environment. name="id" type="string" description="The target commit id to promote to the subsequent environment." -/> + /> ### Returns @@ -2340,18 +2336,18 @@ A promoted commit. ```json Response { - "commit": { - "id": "e4a22631-e05e-4d40-b323-4dc327c0670e", - "resource": { - "identifier": "new-comment", - "type": "workflow" - }, - "author": { - "email": "franklin@gmail.com", - "name": "Franklin Sierra" - }, - "environment": "staging" - } + "commit": { + "id": "e4a22631-e05e-4d40-b323-4dc327c0670e", + "resource": { + "identifier": "new-comment", + "type": "workflow" + }, + "author": { + "email": "franklin@gmail.com", + "name": "Franklin Sierra" + }, + "environment": "staging" + } } ``` diff --git a/content/reference.mdx b/content/reference.mdx index 21d2ba26..fb24de6a 100644 --- a/content/reference.mdx +++ b/content/reference.mdx @@ -2430,14 +2430,16 @@ as such return information that is required on the client to do so**
-Retrieves a feed of items for a given `user_id` on the given `feed_id`. +Retrieves a feed of items in reverse chronological order for a given `user_id` on the given `in_app_feed_channel_id`. In the case where the user has not yet been identified within Knock, this endpoint will return an empty feed. + +You can customize the response for this endpoint by using [response filters](/integrations/in-app/knock#customizing-api-response-content) to exclude or only include certain properties on your resources. **Note: if you're making this call from a client-side environment you should be using your publishable key along with a user token to make this request** ### Endpoint - + ### Rate limit diff --git a/content/send-notifications/message-statuses.mdx b/content/send-notifications/message-statuses.mdx index 3af6dcfc..789de7fa 100644 --- a/content/send-notifications/message-statuses.mdx +++ b/content/send-notifications/message-statuses.mdx @@ -20,9 +20,7 @@ You can use the "Logs" tab in the message detail view in the Knock dashboard to ![Knock message delivery status lifecycle](/images/notifications/delivery-status-lifecycle.png) -
- Figure 1 — The Knock message delivery status lifecycle. -
+
Figure 1 — The Knock message delivery status lifecycle.
Figure 1 above illustrates the full delivery status lifecycle. As the diagram implies, a message can only ever have one delivery status at a time. Plus, not all delivery statuses are available to all channels. @@ -69,7 +67,7 @@ We've received confirmation from the delivery provider that your message was suc On a per-channel level, `delivered` means that: - **Email** — Your message was successfully delivered to the recipient's email service provider. -- **In-app** — Your message was successfully delivered to the recipient's feed. +- **In-app** — Your message was successfully delivered to the recipient's feed. - **Push** — We do not support delivery tracking for push channels, so push channel messages will never have a delivery status greater than `sent`. You can set up delivery tracking by introducing a handler into your mobile app to tell Knock when the message has successfully made it to your recipient's device. - **SMS** — Your message was successfully sent to the recipient's SMS provider. Note that not all SMS delivery providers support delivery tracking. See the [Knock integration guides for SMS providers](/integrations/sms/overview) for more information. - **Chat** — Delivery tracking is not available for chat platforms, so chat channel messages will never have a delivery status greater than `sent`. In most cases, a `sent` status will also mean that the message has been delivered to the recipient. @@ -89,7 +87,7 @@ Below we review the possible engagement statuses and various per-channel caveats ### Seen | Timestamp field | Badge | -|-----------------|--------| +| --------------- | ------ | | `seen_at` | `seen` | Knock only implicitly manages this status for the in-app feed channel. @@ -99,7 +97,7 @@ The `seen` status indicates that the message has been retrieved for display in t ### Marked as read / opened | Timestamp field | Badge | -|-----------------|--------| +| --------------- | ------ | | `read_at` | `read` | The message has been opened and read by the recipient at least once. The timestamp represents the time of the most recent action. @@ -107,7 +105,7 @@ The message has been opened and read by the recipient at least once. The timesta Knock will implicitly manage this status only for the following channel configurations: - **Email** — [Knock open tracking](/send-notifications/tracking) needs to be enabled. -- **In-app** — When you're using the [Knock ReactFeedProvider SDK](/in-app-ui/react/feed). +- **In-app** — When you're using the [Knock ReactFeedProvider SDK](/in-app-ui/react/feed). - **Push** — Not currently supported. - **SMS** — Not directly supported. But, if [Knock link tracking](/send-notifications/tracking) is enabled, we will count a link-click action as also an open event. - **Chat** — Not directly supported. But, if [Knock link tracking](/send-notifications/tracking) is enabled, we will count a link-click action as also an open event. @@ -115,10 +113,9 @@ Knock will implicitly manage this status only for the following channel configur ### Link clicked | Timestamp field | Badge | -|-------------------------------------|----------------| +| ----------------------------------- | -------------- | | `link_clicked_at` -or- `clicked_at` | `link_clicked` | - A link within your message was clicked by the recipient. The timestamp represents the time of the most recent action. Knock will implicitly manage this status only for the following channel configurations: @@ -132,7 +129,7 @@ Knock will implicitly manage this status only for the following channel configur ### Interacted | Timestamp field | Badge | -|-----------------|--------------| +| --------------- | ------------ | | `interacted_at` | `interacted` | Knock only implicitly manages this status for the in-app feed channel. @@ -142,7 +139,7 @@ For the in-app feed case, this indicates that your recipient has explicitly clic ### Archived | Timestamp field | Badge | -|-----------------|------------| +| --------------- | ---------- | | `archived_at` | `archived` | Knock only implicitly manages this status for the in-app feed channel. diff --git a/package.json b/package.json index 43925081..1d9e7a9e 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "export": "next export", "lint": "next lint", "type-check": "tsc", - "format": "prettier \"**/*.+(ts|js|tsx)\"", + "format": "prettier \"**/*.+(ts|js|tsx|mdx|md)\"", "format.write": "yarn run format --write", "format.check": "yarn run format --check" },