in-app-ui

Knock 应用内 UI 技能

此技能可帮助你使用 Knock 构建应用内 UI。它会概述两款应用内产品——信息流和引导，然后深入介绍引导：Provider 设置、使用钩子渲染以及调试。

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

概述

此技能分为四个专门的规则文件。针对客户端框架的指南会通过 -<framework> 后缀按框架划分（目前只有 React）。跨框架概念则放在没有后缀的文件中。

1. 信息流与引导（与框架无关）——针对特定界面应选择哪款产品，以及原因
2. 在 React 中设置引导 Provider——KnockProvider 和 KnockGuideProvider 的属性、各项值的来源，以及设置顺序
3. 在 React 中渲染引导——使用 useGuide / useGuides 构建引导组件、处理类型化内容和跟踪互动
4. 调试引导（与框架无关）——引导工具栏、排查清单和测试工作流

**框架范围：**目前，此技能仅涵盖 React（@knocklabs/react）。如果用户使用 Vue、Svelte、纯 JS、React Native、iOS 或 Android 构建，请停下来询问他们希望如何继续——不要自行将 React 规则套用到其他客户端 SDK 上。

如何使用此技能

决定要构建什么

从 rules/feeds-vs-guides.md 开始：

• 确认你要构建的界面确实是引导，而不是信息流
• 选择方案前，先查看决策表
• 如果答案是“两者都需要”，则只需在应用外层包装一次 KnockProvider，并在需要的位置分别渲染各产品的 Provider

首次将指南添加到 React 应用时

1. 阅读 rules/setup-guide-providers-react.md
2. 运行任何 CLI 命令之前，请确认 CLI 已完成身份验证，并确认此次设置使用哪个 Knock 环境。 先运行 knock whoami——如果出现类似“not authenticated”或“no user session”的错误，请运行 knock login，并让用户完成浏览器流程后再继续（CLI 会保存会话，因此每台机器只需执行一次）。只有在 knock whoami 成功后，才运行 knock environment list 并让用户选择环境（CLI 默认使用 development，但大多数实际集成面向 production）。记下该环境的 slug，作为 <env-slug>，并在之后每条限定环境的 knock 命令中传入 --environment <env-slug>。
3. 在询问用户任何有关频道的问题之前，先通过 Knock CLI 查找 channelId： 运行 knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'。频道的作用范围是账户，因此此命令不需要 --environment。如果命令输出 UUID，请直接使用——不要让用户确认或重新粘贴。只有在 CLI 没有返回结果或出错时才询问用户。完整的备用查找顺序请参阅规则文件中的“Where to get channelId”流程。
4. 只向用户询问无法自动查找的值——主要是所选环境的公开 apiKey（并确认 user.id 来自应用的身份验证上下文）。不要把询问 apiKey 和 channelId 合在一起。
5. 在组件树顶部接入 KnockProvider + KnockGuideProvider。
6. 如果定位依赖任何异步数据，请据此设置 readyToTarget 的条件。
7. 停止之前，确保有真实指南完成渲染。 运行 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 → “First guide: discover real guides via CLI before writing code”。
8. 明确指出仍需用户完成的事项（粘贴 pk_ 密钥、在控制面板中将指南切换为 active、重启开发服务器）——不要让用户因为缺少提示而自行发现。

在 React 中构建新的指南组件时

1. 遵循 rules/rendering-guides-react.md 中的工作流程
2. 在选择值之前，通过 Knock CLI 查找目标指南（或消息类型）。 使用 knock guide list --environment <env-slug> --json 获取指南的 key / 步骤的 schema_key；使用 knock message-type get <schema_key> --environment <env-slug> --json 获取内容 schema。避免使用占位字符串。
3. 单个指南界面使用 useGuide，列表使用 useGuides
4. 定义一个 TypeScript 类型，使其与刚获取的消息类型 schema 一致
5. 接入 markAsSeen、markAsInteracted 和 markAsArchived——自定义组件必须自行调用这些方法

指南未渲染时

1. 打开 rules/debugging-guides.md，从头到尾完成排查清单
2. 先启用指南工具栏（?knock_guide_toolbar=true）——它能在几秒内解答大多数问题
3. 在深入排查之前，先区分服务端（定位/资格判断）故障与客户端（提供程序/组件）故障

规则文件参考

• 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 — 工具栏、排查清单、测试工作流（与框架无关）

快速参考

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

Providers（最低可行配置 — React）

<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>

各值的来源

• 先验证身份，再选择环境 — Knock 按环境区分。在运行任何 CLI 命令前，先用 knock whoami 确认 CLI 已完成身份验证；如果报错，运行 knock login，并等待用户完成浏览器流程。然后运行 knock environment list，与用户确认目标 slug（production、development 等）。后续每条按环境区分的 knock 命令都要传入 --environment <env-slug>。不要依赖 CLI 默认使用的 development。

• apiKey — Knock 控制面板 → Platform → API keys → 公开的 pk_... key，需从所选环境对应的标签页获取（先通过控制面板的环境选择器切换环境；提醒用户复制正确环境的 key）

• user.id — 你的身份验证上下文；必须与后端识别用户时使用的 id 一致

• channelId — guide channel 的 UUID，而不是它的 key。Channels 按账户区分，因此 knock channel list 不需要 --environment。务必先尝试通过 CLI 查找，再询问用户：

  knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
  

  如果此命令输出 UUID，直接使用，无需提示用户确认。默认的 guide channel key 是 knock-guide（类型为 in_app_guide）。只有当 CLI 没有返回结果或报错时，才转而查看控制面板（Settings → Integrations → Channels）。完整流程请参阅 rules/setup-guide-providers-react.md。

Hooks 一览

• useGuide({ type }) — 按消息类型获取一个 guide
• useGuide({ key }) — 按 key 获取一个特定 guide
• useGuides({ type }) — 按消息类型获取一组 guides
• useGuideContext() — 底层客户端访问

互动方法

• step.markAsSeen() — 曝光（在以 step 为依赖的 useEffect 中调用）
• step.markAsInteracted() — 主要操作
• step.markAsArchived() — 忽略；此后会为该用户移除该 guide

遇到问题时的第一步

在任意 URL 后添加 ?knock_guide_toolbar=true。工具栏会显示所有 guides、哪些处于激活状态、该用户符合哪些 guide 的条件，以及其他 guide 被筛除的原因。

最佳实践摘要

1. 选择合适的产品。 时间顺序列表用 feeds，定向 UI 用 guides。
2. 在组件树的较高位置只挂载一次 providers。 将它们置于身份验证边界内、任何会渲染 guides 的路由之上。
3. 绝不传入占位用户。 等待身份验证完成后再挂载 KnockProvider。
4. 根据异步数据控制 readyToTarget，这些数据是定位规则所依赖的。
5. 为内容定义类型。 useGuide<T> 应与 Knock 消息类型架构相匹配。
6. 务必处理互动。 自定义组件必须自行调用 markAsSeen、markAsInteracted 和 markAsArchived。
7. 先使用工具栏。 大多数“guide 没有显示”的问题都能在几秒内找到答案。