diff --git a/content/in-app-ui/guides/render-guides.mdx b/content/in-app-ui/guides/render-guides.mdx index 8e44ea1a1..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 @@ -53,7 +53,7 @@ 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. @@ -61,9 +61,8 @@ When working with Knock's SDKs to fetch and render guides, you'll use the follow - [**useGuideContext**](/in-app-ui/react/sdk/hooks/use-guide-context). Hook to access the guide client for advanced use cases. We're working on adding guides support to more of our client SDKs. Please @@ -98,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 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, 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. 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. The `useGuides` hook is designed to return multiple guides, so it does not apply throttling rules. @@ -116,8 +115,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 +141,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..a3579acc8 100644 --- a/content/in-app-ui/react/headless/guide.mdx +++ b/content/in-app-ui/react/headless/guide.mdx @@ -64,6 +64,22 @@ Using our `@knocklabs/react` and `@knocklabs/client` libraries, you can create f }; ``` + + 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/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..7d6519d01 --- /dev/null +++ b/typedocs/react-core/components/knock-guide-location-sensor.mdx @@ -0,0 +1,59 @@ +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 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. + +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 title="Next.js implementation of KnockGuideLocationSensor." +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 title="Tanstack Router implementation of KnockGuideLocationSensor." +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} > - + );