knock-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 命令前，先确认身份验证状态并检查账户环境。 先运行 knock whoami——如果报错提示类似“not authenticated”或“no user session”，请运行 knock login，并让用户完成浏览器流程后再继续。然后运行 knock environment list。如果返回一个环境，就使用该默认环境（新账户的默认环境为生产环境）；如果返回多个环境，请让用户选择。记下 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_ 密钥、在仪表板中将指南切换为启用状态、重启开发服务器）——不要让用户因缺少提示而自行发现。

在 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 验证身份；如果报错，运行 knock login 并等待浏览器流程完成。然后运行 knock environment list。如果只返回一个环境，则自动使用该环境；如果返回多个环境，则请用户选择。后续每条环境范围内的命令都要传入 --environment <env-slug>；否则 CLI 会使用账户的默认环境。

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

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

• channelId — 指南频道的 UUID，而非其键。频道的范围是账户级，因此 knock channel list 不需要传入 --environment。请务必先尝试通过 CLI 查找，再询问用户：

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

  如果此命令输出 UUID，请直接使用，无需请求确认。默认指南频道键为 knock-guide（类型为 in_app_guide）。只有在 CLI 没有返回结果或报错时，才回退到控制面板（Settings → Integrations → Channels）。完整流程请参阅 rules/setup-guide-providers-react.md。

Hooks 一览

• useGuide({ type }) — 获取一条指定消息类型的指南
• useGuide({ key }) — 获取一条指定键的指南
• useGuides({ type }) — 获取指定消息类型的指南数组
• useGuideContext() — 低层级客户端访问

互动方法

• step.markAsSeen() — 记录展示（在以 step 为依赖项的 useEffect 中调用）
• step.markAsInteracted() — 记录主要操作
• step.markAsArchived() — 记录关闭；此后该用户将不再看到此指南

出现问题时的第一步

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

最佳实践摘要

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