From 2572c74f6eb74dff7c73f27acb441d2588a7fcd9 Mon Sep 17 00:00:00 2001 From: Thomas Date: Wed, 5 Nov 2025 16:37:04 -0500 Subject: [PATCH 1/2] add a page for KnockGuideLocationSensor, along with a few guide edits --- content/in-app-ui/guides/render-guides.mdx | 14 +++-- content/in-app-ui/react/headless/guide.mdx | 1 + .../knock-guide-location-sensor.mdx | 7 +++ data/sidebars/inAppSidebar.ts | 1 + .../knock-guide-location-sensor.mdx | 56 +++++++++++++++++++ .../components/knock-guide-provider.mdx | 2 +- 6 files changed, 74 insertions(+), 7 deletions(-) create mode 100644 content/in-app-ui/react/sdk/components/knock-guide-location-sensor.mdx create mode 100644 typedocs/react-core/components/knock-guide-location-sensor.mdx diff --git a/content/in-app-ui/guides/render-guides.mdx b/content/in-app-ui/guides/render-guides.mdx index 8e44ea1a1..10dd30966 100644 --- a/content/in-app-ui/guides/render-guides.mdx +++ b/content/in-app-ui/guides/render-guides.mdx @@ -53,13 +53,15 @@ Knock exposes a set of client SDKs that provide helpers and logic to make it eas #### Key SDK resources -When working with Knock's SDKs to fetch and render guides, you'll use the following components and hooks: +When working with Knock's SDKs to fetch and render guides, you'll use the following components and hooks for React: - [**KnockGuideProvider**](/in-app-ui/react/sdk/components/knock-guide-provider). Provider component that fetches guides and manages guide state. - [**useGuide**](/in-app-ui/react/sdk/hooks/use-guide). Hook to fetch a single guide by type or key. - [**useGuides**](/in-app-ui/react/sdk/hooks/use-guides). Hook to fetch multiple guides. - [**useGuideContext**](/in-app-ui/react/sdk/hooks/use-guide-context). Hook to access the guide client for advanced use cases. +Follow this [step-by-step example](/in-app-ui/react/headless/guide) to set up the provider and render your guide components in your React application. + - The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook fetches a single guide at a time. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI. + The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook returns a single guide at a time, subject to eligibility criteria. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI. -The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar. +The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria, in the configured order. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar. Note, unlike the `useGuide` hook, `useGuides` does not apply throttling given multiple guides can be returned. @@ -116,8 +118,8 @@ The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or mor
{guides.map((guide) => (
-

{guide.step.content.title}

-

{guide.step.content.body}

+

{guide.steps[0].content.title}

+

{guide.steps[0].content.body}

))}
@@ -142,5 +144,5 @@ The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or mor To see which guides are actually eligible to be rendered, check the `entries` array in the API response, which contains only the guides that match all criteria for the current user and context. - + diff --git a/content/in-app-ui/react/headless/guide.mdx b/content/in-app-ui/react/headless/guide.mdx index 13a4ff7df..f60472ab6 100644 --- a/content/in-app-ui/react/headless/guide.mdx +++ b/content/in-app-ui/react/headless/guide.mdx @@ -63,6 +63,7 @@ Using our `@knocklabs/react` and `@knocklabs/client` libraries, you can create f ); }; ``` + Also, if you are using Next.js or Tanstack Router, consider using the [KnockGuideLocationSensor](/in-app-ui/react/sdk/components/knock-guide-location-sensor) helper component inside `KnockGuideProvider` to facilitate evalutating activation rules based on route changes. diff --git a/content/in-app-ui/react/sdk/components/knock-guide-location-sensor.mdx b/content/in-app-ui/react/sdk/components/knock-guide-location-sensor.mdx new file mode 100644 index 000000000..a9aff1fd6 --- /dev/null +++ b/content/in-app-ui/react/sdk/components/knock-guide-location-sensor.mdx @@ -0,0 +1,7 @@ +--- +title: KnockGuideLocationSensor +description: +section: SDKs +--- + + diff --git a/data/sidebars/inAppSidebar.ts b/data/sidebars/inAppSidebar.ts index 801e07e3e..ec2bb0a1d 100644 --- a/data/sidebars/inAppSidebar.ts +++ b/data/sidebars/inAppSidebar.ts @@ -122,6 +122,7 @@ const SHARED_REACT_COMPONENTS = [ { slug: "/knock-provider", title: "KnockProvider" }, { slug: "/knock-feed-provider", title: "KnockFeedProvider" }, { slug: "/knock-guide-provider", title: "KnockGuideProvider" }, + { slug: "/knock-guide-location-sensor", title: "KnockGuideLocationSensor" }, { slug: "/knock-slack-provider", title: "KnockSlackProvider" }, { slug: "/knock-ms-teams-provider", title: "KnockMsTeamsProvider" }, { slug: "/knock-i18n-provider", title: "KnockI18nProvider" }, diff --git a/typedocs/react-core/components/knock-guide-location-sensor.mdx b/typedocs/react-core/components/knock-guide-location-sensor.mdx new file mode 100644 index 000000000..b032a23c4 --- /dev/null +++ b/typedocs/react-core/components/knock-guide-location-sensor.mdx @@ -0,0 +1,56 @@ +A React helper component intended for use with select supported frameworks, such as [Next.js](https://nextjs.org/) and [Tanstack Router](https://tanstack.com/router/), for detecting route changes. + +Activation rules for guides are evaluated as user's location changes in your application, and [KnockGuideProvider](/in-app-ui/react/sdk/components/knock-guide-provider) by default listens for location change events from the global `window` object (enabled via the `trackLocationFromWindow` prop). + +However, modern frameworks often provide their own first class router API for detecting and reacting to route changes that can work better and more reliably. Note the import path specific to a corresponding framework, and also `KnockGuideLocation` must be placed inside `KnockGuideProvider`. + +## Usage + +### Next.js + +```jsx +import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core"; +import { KnockGuideLocationSensor } from "@knocklabs/react/next"; + +function App() { + return ( + + + + // Must be placed inside KnockGuideProvider. + + // If you are using the Pages Router: // + + + ); +} +``` + +### Tanstack Router + +```jsx +import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core"; +import { KnockGuideLocationSensor } from "@knocklabs/react/tanstack"; + +function App() { + return ( + + + + // Must be placed inside KnockGuideProvider. + + + + ); +} +``` diff --git a/typedocs/react-core/components/knock-guide-provider.mdx b/typedocs/react-core/components/knock-guide-provider.mdx index c9fbf696e..93aab3218 100644 --- a/typedocs/react-core/components/knock-guide-provider.mdx +++ b/typedocs/react-core/components/knock-guide-provider.mdx @@ -15,7 +15,7 @@ function App() { colorMode="auto" trackLocationFromWindow={true} > - + ); From 819d92f3c6b63ad6d4c0332b8b8a6c2bf409eb79 Mon Sep 17 00:00:00 2001 From: Scoti Dodson Date: Wed, 5 Nov 2025 17:27:59 -0500 Subject: [PATCH 2/2] example viz, copy edits --- content/in-app-ui/guides/render-guides.mdx | 11 ++++------- content/in-app-ui/react/headless/guide.mdx | 17 ++++++++++++++++- .../components/knock-guide-location-sensor.mdx | 11 +++++++---- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/content/in-app-ui/guides/render-guides.mdx b/content/in-app-ui/guides/render-guides.mdx index 10dd30966..61447abcb 100644 --- a/content/in-app-ui/guides/render-guides.mdx +++ b/content/in-app-ui/guides/render-guides.mdx @@ -9,7 +9,7 @@ Once you've [created a guide](/in-app-ui/guides/create-guides), you'll need to r ## Fetching guides -You can fetch guides using Knock's client-side SDKs or by directly calling the [guides API](/api-reference/users/guides). +There are two ways to fetch and render guides: using Knock's client-side SDKs, which provide built-in state management and helper methods, or by directly calling the [guides API](/api-reference/users/guides) to build a custom implementation. Our [step-by-step React example](/in-app-ui/react/headless/guide) demonstrates how to incorporate the SDK's guide provider into your application and render guide components to your users. ### Client-side SDKs @@ -60,12 +60,9 @@ When working with Knock's SDKs to fetch and render guides, you'll use the follow - [**useGuides**](/in-app-ui/react/sdk/hooks/use-guides). Hook to fetch multiple guides. - [**useGuideContext**](/in-app-ui/react/sdk/hooks/use-guide-context). Hook to access the guide client for advanced use cases. -Follow this [step-by-step example](/in-app-ui/react/headless/guide) to set up the provider and render your guide components in your React application. - We're working on adding guides support to more of our client SDKs. Please @@ -100,9 +97,9 @@ When multiple guides exist for a single `type` (e.g, a generic "Banner" componen - The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook returns a single guide at a time, subject to eligibility criteria. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI. + The [`useGuide`](/in-app-ui/react/sdk/hooks/use-guide) hook returns a single guide at a time, subject to eligibility criteria, throttling rules, and ordering. This is ideal for components that should only display one guide, like a banner or modal that occupies a specific location in your UI. -The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria, in the configured order. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar. Note, unlike the `useGuide` hook, `useGuides` does not apply throttling given multiple guides can be returned. +The [`useGuides`](/in-app-ui/react/sdk/hooks/use-guides) hook fetches one or more guides, subject to eligibility criteria, in the configured order. This is useful for components that can display multiple guides at once, like a list of changelog cards or announcements in a sidebar. The `useGuides` hook is designed to return multiple guides, so it does not apply throttling rules. diff --git a/content/in-app-ui/react/headless/guide.mdx b/content/in-app-ui/react/headless/guide.mdx index f60472ab6..a3579acc8 100644 --- a/content/in-app-ui/react/headless/guide.mdx +++ b/content/in-app-ui/react/headless/guide.mdx @@ -63,8 +63,23 @@ Using our `@knocklabs/react` and `@knocklabs/client` libraries, you can create f ); }; ``` - Also, if you are using Next.js or Tanstack Router, consider using the [KnockGuideLocationSensor](/in-app-ui/react/sdk/components/knock-guide-location-sensor) helper component inside `KnockGuideProvider` to facilitate evalutating activation rules based on route changes. + + consider using the{" "} + + KnockGuideLocationSensor + + {` `} + helper component inside KnockGuideProvider to facilitate + evaluating activation rules based on route changes. + + } +/> +> If you're not using one of our pre-built message types, you'll need to set up a custom message type. You can learn more about how to do this in our [message types](/in-app-ui/message-types/create-message-types) documentation. diff --git a/typedocs/react-core/components/knock-guide-location-sensor.mdx b/typedocs/react-core/components/knock-guide-location-sensor.mdx index b032a23c4..7d6519d01 100644 --- a/typedocs/react-core/components/knock-guide-location-sensor.mdx +++ b/typedocs/react-core/components/knock-guide-location-sensor.mdx @@ -1,14 +1,17 @@ A React helper component intended for use with select supported frameworks, such as [Next.js](https://nextjs.org/) and [Tanstack Router](https://tanstack.com/router/), for detecting route changes. -Activation rules for guides are evaluated as user's location changes in your application, and [KnockGuideProvider](/in-app-ui/react/sdk/components/knock-guide-provider) by default listens for location change events from the global `window` object (enabled via the `trackLocationFromWindow` prop). +Activation rules for guides are evaluated as a user's location changes in your application and, by default, [KnockGuideProvider](/in-app-ui/react/sdk/components/knock-guide-provider) listens for location change events from the global `window` object (enabled via the `trackLocationFromWindow` prop). However, modern frameworks often provide their own first class router APIs for detecting and reacting to route changes, which often works better and more reliably. -However, modern frameworks often provide their own first class router API for detecting and reacting to route changes that can work better and more reliably. Note the import path specific to a corresponding framework, and also `KnockGuideLocation` must be placed inside `KnockGuideProvider`. +Two important notes to keep in mind when implementing `KnockGuideLocationSensor`: + +1. The import path is specific to the corresponding framework (e.g., `@knocklabs/react/next` for Next.js). +2. `KnockGuideLocationSensor` must be placed inside `KnockGuideProvider`. ## Usage ### Next.js -```jsx +```jsx title="Next.js implementation of KnockGuideLocationSensor." import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core"; import { KnockGuideLocationSensor } from "@knocklabs/react/next"; @@ -33,7 +36,7 @@ function App() { ### Tanstack Router -```jsx +```jsx title="Tanstack Router implementation of KnockGuideLocationSensor." import { KnockProvider, KnockGuideProvider } from "@knocklabs/react-core"; import { KnockGuideLocationSensor } from "@knocklabs/react/tanstack";