集成指南

无差错安装 — 你自己来，或交给你的 AI 代理。

AppKit 能做的一切、每样东西出现在哪里，以及一个可直接粘贴到编码助手的现成 prompt。你不会做的部分，交给代理替你完成。

01给你的 AI 代理的 prompt

把下面的文字粘贴到你的编码助手中，将 MINHA_CHAVE_PK_LIVE 换成你控制台里的密钥，它就会完成整个集成 — 安装、空状态和步骤完成 — 而不破坏你的产品。

Claude Code Antigravity OpenAI / Codex Cursor, Copilot…

prompt-appkit.txt

你是我的编码助手。请将 AppKit（appkit.com.br）集成到我的 web 产品中，且不得破坏任何东西。AppKit 会注入一个 onboarding checklist、空状态和公告，由外部控制台管理。请严格按以下步骤执行：

1) 安装
- 如果项目使用 bundler（React/Vue/Next/Svelte 等）：安装此包
  @tecaless/appkit-sdk
  并在入口文件中、用户登录之后（当我已拿到其 id 时）调用：
  import { init } from '@tecaless/appkit-sdk'
  init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: <已登录用户的稳定 id> })
- 如果是静态网站 / no-code：在  之前加入：
  
- userId/data-user 必须是已登录用户的稳定标识符。AppKit 会在服务器上将其转为 hash — 绝不要发送邮箱或姓名。如果没有已登录用户，就不要传 userId。

2) 空状态
对每个初始无数据、且我想要行动召唤的页面（如发票、联系人、日程），把当前的空状态包进一个带标记的容器中，并保留现有内容作为 fallback：
   ...现有的“没有记录”内容... 
每个页面用一个简短稳定的名称（如 faturas-vazio、contatos-vazio）。不要使用构建生成的 CSS 选择器。最后把你创建的名称列表返回给我。

3) 步骤完成（对真实指标很重要）
对每个代表用户真实行为的 onboarding 步骤（如“开出第一张发票”），在行为真正落实的那一刻调用 — 在服务器保存之后，而不是按钮点击时：
  window.AppKit && window.AppKit.track('fatura_emitida')
每个行为用一个事件名，snake_case 格式。最后把你创建的事件列表返回给我。

4) 不要破坏任何东西
- 异步加载 SDK；它是 fail-open 的（如果它挂了，会自行消失，不影响我的产品）。
- pk_live 密钥天生是公开的（可以放在客户端）。不要暴露任何机密密钥。
- 不要为等待 AppKit 而阻塞渲染。

最后列出：(a) 修改过的文件，(b) 创建的 data-appkit 名称，(c) 创建的事件名称 — 供我在 AppKit 控制台中配置。

代理完成后，用它返回给你的 data-appkit 名称和事件名称，在控制台中配置空状态和步骤完成。

02安装

两种方式。如果你使用框架，从 npm 开始。

使用 bundler（React、Vue、Next、Svelte…）— 推荐

terminal

npm i @tecaless/appkit-sdk

app.js — 登录之后

import { init, track } from '@tecaless/appkit-sdk'

init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: usuario.id })
// 当真实行为发生时：
track('fatura_emitida')

No-code / 静态网站 — 一行代码

在 </body> 之前

<script src="https://appkit.com.br/sdk/appkit@3.0.7.js"
        data-key="MINHA_CHAVE_PK_LIVE"
        data-user="ID_DO_USUARIO" async></script>

你的 pk_live_… 密钥在控制台的安装页。它天生是公开的（只能读取你的配置和发送事件）。

03每样东西出现在哪里

这三种体验可在你产品的任何页面上运行，只要在你安装的域名内。一切都由控制台控制，无需重新 deploy。

Checklist

角落里的浮动卡片。出现在任何页面；用户全部完成后会自行消失。

公告

顶部横幅，会将内容向下推挤（不会遮挡）。可以带链接。你可以随时发布和撤下。

空状态

你的产品显示“没有记录”的地方 — 无需你动代码（你的代理会处理）。它会变成行动召唤。

04空状态：你不需要动代码

空状态的魔力在于无需声明任何东西。点击复制 prompt，你的 AI 代理会处理技术部分：它指向你系统中已存在的元素（通过选择器，不动 HTML），或在需要时添加一个稳定标记 — AppKit 两者都接受。之后你只需在控制台里编辑文案，永久有效，无需 deploy。

用户在 AppKit（appkit.com.br）的“空状态”功能中点击了“复制 prompt”。他希望产品中一个初始无数据的页面变成行动召唤，且无需手动改代码。请执行：

前提 — 必须已安装 AppKit。若尚未安装，请先安装：
  npm i @tecaless/appkit-sdk
  import { init } from '@tecaless/appkit-sdk'; init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: <已登录用户的 id> })
  （或 no-code： 放在  之前）

空状态 — 在代码中找到初始为空的页面（如发票/联系人列表），并选择 AppKit 在那里锚定的方式（两种都可以）：
  (a) 通过稳定的 CSS 选择器（id 或语义类名）指向一个已存在的元素 — 不动 HTML；或
  (b) 如果只有构建生成的类名，就把空状态包进 …现有内容….
把每个空状态的选择器/名称（如 "#faturas-vazio" 或 "faturas-vazio"）返回给我，供我粘贴到控制台 → 空状态。

AppKit 可用功能（在控制台 https://appkit.com.br/painel 中逐一启用）：新手引导 checklist、空状态、顶部公告，以及基于事件的步骤完成（在真实行为发生的那一刻调用 window.AppKit.track('acao_real')）。完整指南：https://appkit.com.br/guia

不要破坏任何东西：异步加载，SDK 是 fail-open 的，pk_live 密钥是公开的（不要暴露机密密钥）。最后列出修改过的文件和创建的选择器/名称。

如果有一天锚点消失了，AppKit 会通知你（appkit_anchor_missing 事件）并且什么都不渲染 — 你的页面保持正常。

05一个步骤如何完成

三种模式，在控制台按步骤选择。这决定你的激活漏斗衡量的是真实行为还是仅仅点击。

真实

按事件

你的代码在真实行为发生的那一刻调用 AppKit.track('acao')。无法造假 — 这才是可用作增长牵引的指标。

proxy

按路由

用户到达某个路由（如 /faturas/nova）。是真实信号，但“到达”不等于“做了”。

可有可无

手动

用户点击条目来勾选。适用于信息型步骤（“读一读这个”）。它是有意可造假的。

要让你的增长分析有意义，重要步骤必须是按事件的。如果是手动的，你衡量的是“用户点了完成”，而不是“用户做了”。

06保障

失败即隐藏：如果 AppKit 挂了，widget 会消失，你的产品保持原样。我们的错误不会进入你的 console。
轻量且隔离：约 10 KB，位于 Shadow DOM 中。不碰你的 CSS，也不与你的页面加载抢资源。
关闭按钮：在控制台点击一下，30 秒内即可从你的所有用户处移除 AppKit，无需 deploy。
设计即符合 LGPD：你的用户 id 在写入数据库之前会变成不可逆的 hash（SHA-256 + 每账户 salt）。绝不要发送邮箱或姓名。
可审计：SDK 通过固定 URL 提供，并有公开的 npm 包。

07常见错误（以及如何避免）

Widget 不显示

检查 data-key，并确认体验在控制台中已发布（不是草稿）。

空状态不显示

HTML 中缺少 data-appkit="…"，或控制台中的名称与代码中的不一致。

步骤不会自动完成

“按路由”规则的路由为空，或“按事件”规则在你的代码里没有在正确时机调用 track()。

用户姓名被显示出来

不要在体验标题或 data-user 中放姓名/邮箱 — 请使用稳定的 id。

还有疑问？contato@appkit.com.br。