in-app-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Knock in-app UI skill

Knock内嵌UI技能指南

This skill helps you build in-app UI with Knock. It covers the two in-app products — feeds and guides — at a high level, then goes deep on guides: provider setup, rendering with hooks, and debugging.

Reference: https://docs.knock.app/in-app-ui/overview

本技能指南帮助你使用Knock构建内嵌UI。它概览了两款内嵌产品——feeds和guides，然后深入讲解guides：提供者设置、使用hooks渲染以及调试。

参考文档：https://docs.knock.app/in-app-ui/overview

Overview

概述

The skill is organized into four focused rule files. Client-framework guidance is scoped per framework via a

-<framework>

suffix (currently only React). Cross-framework concepts live in unsuffixed files.

Feeds vs. guides (framework-agnostic) — which product to pick for a given surface and why
Setting up the guide providers in React —
```
KnockProvider
```
and
```
KnockGuideProvider
```
props, where each value comes from, and how to sequence them
Rendering guides in React — building a guide component with
```
useGuide
```
/
```
useGuides
```
, typed content, and engagement tracking
Debugging guides (framework-agnostic) — the guides toolbar, the triage checklist, and testing workflow

Framework scope: right now this skill only covers React (
@knocklabs/react
). If the user is building with Vue, Svelte, plain JS, React Native, iOS, or Android, stop and ask how they'd like to proceed — do not adapt the React rules to another client SDK on your own.

本技能指南分为四个聚焦规则文件。客户端框架相关指南通过

-<framework>

后缀区分（目前仅支持React）。跨框架概念存放在无后缀的文件中。

Feeds vs. guides（跨框架通用）——针对特定场景选择合适产品的原因
在React中设置引导组件提供者——
```
KnockProvider
```
和
```
KnockGuideProvider
```
的属性、各属性值的来源以及它们的加载顺序
在React中渲染引导组件——使用
```
useGuide
```
/
```
useGuides
```
构建引导组件、类型化内容以及互动追踪
调试引导组件（跨框架通用）——引导组件工具栏、分类检查清单和测试流程

**框架范围说明：**目前本技能指南仅覆盖React（
@knocklabs/react
）。如果用户使用Vue、Svelte、原生JS、React Native、iOS或Android进行开发，请暂停并询问用户的下一步需求——请勿自行将React规则适配到其他客户端SDK。

How to use this skill

如何使用本技能指南

When deciding what to build

决定构建内容时

Start with

rules/feeds-vs-guides.md

Confirm the surface you're building is actually a guide, not a feed
Check the decision table before picking a direction
If the answer is "both," wrap the app in
```
KnockProvider
```
once and render each product's provider where it's needed

从

rules/feeds-vs-guides.md

开始：

确认你要构建的场景确实是guide而非feed
在选择方向前查看决策表
如果需要同时使用两者，只需在应用中包裹一次
```
KnockProvider
```
，并在需要的地方渲染对应产品的提供者

When adding guides to a React app for the first time

首次在React应用中添加引导组件时

Read
```
rules/setup-guide-providers-react.md
```
Before running any CLI commands, confirm the CLI is authenticated and which Knock environment this setup is for. First run
```
knock whoami
```
— if it errors with something like "not authenticated" or "no user session," run
```
knock login
```
and ask the user to complete the browser flow before continuing (the CLI persists the session so this is a one-time step per machine). Only after
```
knock whoami
```
succeeds, run
```
knock environment list
```
and ask the user to pick (the CLI defaults to
```
development
```
, but most real integrations target
```
production
```
). Remember that slug as
```
<env-slug>
```
and pass
```
--environment <env-slug>
```
on every subsequent environment-scoped
```
knock
```
command.
Before asking the user anything about the channel, discover
channelId
via the Knock CLI: run
```
knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
```
. Channels are account-scoped, so this command does not take
```
--environment
```
. If it prints a UUID, use it — do not ask the user to confirm or re-paste. Only ask the user if the CLI returns nothing or errors. See the rule file's "Where to get
```
channelId
```
" procedure for the full fallback order.
Ask the user only for values that can't be auto-discovered — primarily the public
```
apiKey
```
for the chosen environment (and confirm
```
user.id
```
is coming from the app's auth context). Do not bundle the
```
apiKey
```
ask with
```
channelId
```
.
Wire
```
KnockProvider
```
+
```
KnockGuideProvider
```
at the top of the tree.
Gate
```
readyToTarget
```
on any async data your targeting depends on.
Get a real guide rendering before stopping. Run
```
knock guide list --environment <env-slug> --json
```
, show the user the options (
```
key
```
,
```
name
```
, each step's
```
schema_key
```
), and build the first component against a real guide's actual values. Do not scaffold with placeholder strings like
```
"changelog-card"
```
. Fetch the message type schema with
```
knock message-type get <schema_key> --environment <env-slug> --json
```
so the content is typed. If the environment has no guides, offer to scaffold a test one via the Knock CLI (
```
knock guide new
```
→ edit the JSON →
```
knock guide push --environment <env-slug>
```
) using a built-in message type (
```
card
```
,
```
banner
```
, or
```
modal
```
) with obvious-placeholder content — don't stall waiting for manual dashboard setup. See
```
rules/rendering-guides-react.md
```
→ "First guide: discover real guides via CLI before writing code" for the full procedure including the empty-environment branch.
Flag anything that still needs the user (paste
```
pk_
```
key, flip the guide to active in the dashboard, restart dev server) explicitly — don't leave them to discover it by absence.

阅读
```
rules/setup-guide-providers-react.md
```
**在运行任何CLI命令前，确认CLI已认证以及本次设置对应的Knock环境。**先运行
```
knock whoami
```
——如果出现“未认证”或“无用户会话”之类的错误，运行
```
knock login
```
并等待用户完成浏览器端流程后再继续（CLI会持久化会话，因此这是每台机器仅需执行一次的步骤）。只有在
```
knock whoami
```
执行成功后，再运行
```
knock environment list
```
并让用户选择目标环境（CLI默认是
```
development
```
，但大多数实际集成会针对
```
production
```
）。记住该环境的标识为
```
<env-slug>
```
，并在后续所有与环境相关的
```
knock
```
命令中添加
```
--environment <env-slug>
```
参数。
在询问用户任何关于渠道的信息前，通过Knock CLI获取
channelId
：运行
knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
。渠道是账号级别的，因此该命令不需要
```
--environment
```
参数。如果输出UUID，直接使用——无需让用户确认或重新粘贴。只有当CLI无输出或报错时，才询问用户。完整的 fallback 流程请查看规则文件中的“获取
```
channelId
```
的位置”部分。
仅向用户询问无法自动获取的值——主要是所选环境的公开
```
apiKey
```
（并确认
```
user.id
```
来自应用的认证上下文）。不要将
```
apiKey
```
和
```
channelId
```
的询问合并。
在组件树的顶层配置
```
KnockProvider
```
+
```
KnockGuideProvider
```
。
将
```
readyToTarget
```
依赖于你的目标规则所需的任何异步数据。
**确保成功渲染一个真实的引导组件后再停止。**运行
```
knock guide list --environment <env-slug> --json
```
，向用户展示可选的引导组件（
```
key
```
、
```
name
```
、每个步骤的
```
schema_key
```
），并根据真实引导组件的实际值构建第一个组件。不要使用
```
"changelog-card"
```
之类的占位符字符串。使用
```
knock message-type get <schema_key> --environment <env-slug> --json
```
获取消息类型 schema，以便内容类型化。如果环境中没有引导组件，可通过Knock CLI搭建一个测试用引导组件（
```
knock guide new
```
→ 编辑JSON →
```
knock guide push --environment <env-slug>
```
），使用内置消息类型（
```
card
```
、
```
banner
```
或
```
modal
```
）并添加明显的占位符内容——不要等待手动在仪表盘设置而停滞。完整流程包括空环境分支，请查看
```
rules/rendering-guides-react.md
```
→ “第一个引导组件：编写代码前通过CLI发现真实引导组件”部分。
明确标记仍需用户完成的事项（粘贴
```
pk_
```
开头的密钥、在仪表盘将引导组件切换为激活状态、重启开发服务器）——不要让用户自行发现这些遗漏的步骤。

When building a new guide component in React

在React中构建新的引导组件时

Follow the workflow in
```
rules/rendering-guides-react.md
```
Discover the target guide (or message type) via the Knock CLI before picking values.
```
knock guide list --environment <env-slug> --json
```
for the guide's
```
key
```
/ step
```
schema_key
```
;
```
knock message-type get <schema_key> --environment <env-slug> --json
```
for the content schema. Avoid placeholder strings.
Pick
```
useGuide
```
for single-guide surfaces,
```
useGuides
```
for lists
Define a TypeScript type that mirrors the message type schema you just pulled
Wire
```
markAsSeen
```
,
```
markAsInteracted
```
, and
```
markAsArchived
```
— custom components must do this themselves

遵循
```
rules/rendering-guides-react.md
```
中的流程
**在选择值前，通过Knock CLI发现目标引导组件（或消息类型）。**使用
```
knock guide list --environment <env-slug> --json
```
获取引导组件的
```
key
```
/步骤的
```
schema_key
```
；使用
```
knock message-type get <schema_key> --environment <env-slug> --json
```
获取内容schema。避免使用占位符字符串。
单个引导组件场景选择
```
useGuide
```
，列表场景选择
```
useGuides
```
定义一个与你获取到的消息类型schema对应的TypeScript类型
配置
```
markAsSeen
```
、
```
markAsInteracted
```
和
```
markAsArchived
```
——自定义组件必须自行实现这些功能

When a guide isn't rendering

引导组件无法渲染时

Open
```
rules/debugging-guides.md
```
and work the triage checklist top to bottom
Turn on the guides toolbar (
```
?knock_guide_toolbar=true
```
) first — it answers most questions in seconds
Distinguish server-side (targeting/eligibility) from client-side (provider/component) failures before digging deeper

打开
```
rules/debugging-guides.md
```
，从上到下执行分类检查清单
首先开启引导组件工具栏（
```
?knock_guide_toolbar=true
```
）——它能在几秒内解答大多数问题
在深入排查前，先区分服务端（目标定位/资格验证）和客户端（提供者/组件）的故障

Rule files reference

规则文件参考

```
rules/feeds-vs-guides.md
```
— product selection between feeds and guides (framework-agnostic)

rules/setup-guide-providers-react.md

— configuring

KnockProvider

and

KnockGuideProvider

for guides (React)

rules/rendering-guides-react.md

—

useGuide

useGuides

, typed content, engagement tracking (React)

```
rules/debugging-guides.md
```
— toolbar, triage checklist, testing workflow (framework-agnostic)

```
rules/feeds-vs-guides.md
```
——feeds和guides之间的产品选择（跨框架通用）

rules/setup-guide-providers-react.md

——为guides配置

KnockProvider

和

KnockGuideProvider

（React）

```
rules/rendering-guides-react.md
```
——
```
useGuide
```
、
```
useGuides
```
、类型化内容、互动追踪（React）
```
rules/debugging-guides.md
```
——工具栏、分类检查清单、测试流程（跨框架通用）

Quick reference

快速参考

The examples below are React. For any other client SDK, see the note at the top of Overview before proceeding.

以下示例均为React。对于其他客户端SDK，请先查看概述顶部的说明再继续。

Providers (minimum viable setup — React)

提供者（最简可行配置——React）

tsx

<KnockProvider
  apiKey={process.env.NEXT_PUBLIC_KNOCK_API_KEY}
  user={{ id: currentUser.id }}
>
  <KnockGuideProvider
    channelId={process.env.NEXT_PUBLIC_KNOCK_GUIDE_CHANNEL_ID}
    readyToTarget
    listenForUpdates
  >
    {children}
  </KnockGuideProvider>
</KnockProvider>

tsx

<KnockProvider
  apiKey={process.env.NEXT_PUBLIC_KNOCK_API_KEY}
  user={{ id: currentUser.id }}
>
  <KnockGuideProvider
    channelId={process.env.NEXT_PUBLIC_KNOCK_GUIDE_CHANNEL_ID}
    readyToTarget
    listenForUpdates
  >
    {children}
  </KnockGuideProvider>
</KnockProvider>

Where to source each value

各值的来源

Auth first, then environment — Knock is environment-scoped. Before any CLI command, verify the CLI is authenticated with
```
knock whoami
```
; if it errors, run
```
knock login
```
and wait for the user to complete the browser flow. Then run
```
knock environment list
```
and confirm the target slug (
```
production
```
,
```
development
```
, …) with the user. Pass
```
--environment <env-slug>
```
on every subsequent environment-scoped
```
knock
```
command. Don't rely on the CLI's
```
development
```
default.
```
apiKey
```
— Knock dashboard → Platform → API keys → public
```
pk_...
```
key from the tab for the chosen environment (switch envs via the dashboard's environment selector first; remind the user to copy the key for the right env)
```
user.id
```
— your auth context; must match the id used when identifying the user from your backend
```
channelId
```
— the UUID of the guide channel, not its key. Channels are account-scoped, so
```
knock channel list
```
does not take
```
--environment
```
. Always attempt CLI discovery before asking the user:
bash
```
knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
```
If this prints a UUID, use it directly — don't prompt for confirmation. The default guide channel key is
```
knock-guide
```
(type
```
in_app_guide
```
). Fall back to the dashboard (Settings → Integrations → Channels) only if the CLI returns nothing or errors. See
```
rules/setup-guide-providers-react.md
```
for the full procedure.

先认证，再选环境——Knock是按环境划分的。在执行任何CLI命令前，使用
```
knock whoami
```
验证CLI已认证；如果报错，运行
```
knock login
```
并等待用户完成浏览器端流程。然后运行
```
knock environment list
```
并与用户确认目标环境标识（
```
production
```
、
```
development
```
等）。在后续所有与环境相关的
```
knock
```
命令中添加
```
--environment <env-slug>
```
参数。不要依赖CLI默认的
```
development
```
环境。
```
apiKey
```
——Knock仪表盘 → Platform → API keys → 所选环境标签页下的公开
```
pk_...
```
密钥（先通过仪表盘的环境选择器切换到目标环境；提醒用户复制对应环境的密钥）
```
user.id
```
——你的应用认证上下文；必须与后端识别用户时使用的ID一致
```
channelId
```
——guide渠道的UUID，而非其key。渠道是账号级别的，因此
```
knock channel list
```
命令不需要
```
--environment
```
参数。请始终先尝试通过CLI获取，再询问用户：
bash
```
knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
```
如果输出UUID，直接使用——无需提示用户确认。默认的guide渠道key是
```
knock-guide
```
（类型为
```
in_app_guide
```
）。只有当CLI无输出或报错时，才 fallback 到仪表盘（Settings → Integrations → Channels）。完整流程请查看
```
rules/setup-guide-providers-react.md
```
。

Hooks at a glance

Hooks概览

```
useGuide({ type })
```
— one guide by message type
```
useGuide({ key })
```
— one specific guide by key
```
useGuides({ type })
```
— array of guides by message type
```
useGuideContext()
```
— low-level client access

```
useGuide({ type })
```
——按消息类型获取单个引导组件
```
useGuide({ key })
```
——按key获取特定的单个引导组件
```
useGuides({ type })
```
——按消息类型获取引导组件数组
```
useGuideContext()
```
——底层客户端访问

Engagement methods

互动方法

```
step.markAsSeen()
```
— impression (call from
```
useEffect
```
keyed on
```
step
```
)
```
step.markAsInteracted()
```
— primary action
```
step.markAsArchived()
```
— dismissal; removes the guide for this user going forward

```
step.markAsSeen()
```
——记录曝光（在依赖
```
step
```
的
```
useEffect
```
中调用）
```
step.markAsInteracted()
```
——记录主要操作
```
step.markAsArchived()
```
——记录关闭；从此为该用户移除该引导组件

First stop when something's wrong

故障排查第一步骤

Append

?knock_guide_toolbar=true

to any URL. The toolbar shows all guides, which are active, which this user is eligible for, and why the rest were filtered out.

在任意URL后追加

?knock_guide_toolbar=true

。工具栏会显示所有引导组件、哪些处于激活状态、当前用户符合哪些引导组件的条件，以及其余引导组件被过滤的原因。

Best practices summary

最佳实践总结

Pick the right product. Feeds for chronological lists, guides for targeted UI.
Mount providers once, high in the tree. Inside your auth boundary, above any route that renders guides.
Never pass a placeholder user. Wait for auth to resolve before mounting
```
KnockProvider
```
.
Gate
readyToTarget
on async data your targeting rules depend on.
Type your content.
```
useGuide<T>
```
should mirror the Knock message type schema.
Always handle engagement. Custom components must call
```
markAsSeen
```
,
```
markAsInteracted
```
, and
```
markAsArchived
```
themselves.
Use the toolbar first. Most "the guide isn't showing" questions are answered in seconds.

选择合适的产品——feeds用于时序列表，guides用于目标化UI。
在组件树顶层挂载一次提供者——在认证边界内，在所有渲染引导组件的路由之上。
绝不传递占位符用户——等待认证完成后再挂载
```
KnockProvider
```
。
将
readyToTarget
依赖于异步数据——你的目标规则所需的异步数据。
内容类型化——
```
useGuide<T>
```
应与Knock消息类型schema保持一致。
始终处理互动事件——自定义组件必须自行调用
```
markAsSeen
```
、
```
markAsInteracted
```
和
```
markAsArchived
```
。
优先使用工具栏——大多数“引导组件不显示”的问题都能在几秒内得到解答。