Pulse

Pulse SDK

面向 web、React Native、iOS 和 Android 的开源分析 SDK。通过可靠的离线优先事件队列和清晰的身份标识为你的应用添加分析功能——仅此而已。

• 轻巧。 Web SDK 的压缩后体积 ≤ 10 KB，且 零依赖。
• 可靠。 持久、有序的队列可在离线期间和进程退出后保留。投递具有幂等性：重试绝不会导致事件重复。
• 坦诚对待隐私。 不会自动采集，不进行指纹识别，不使用 IDFA/GAID，不集成广告 SDK。SDK 只会发送你提交的事件。
• 一种协议，四个平台。 每个 SDK 都实现相同的 线协议，并在 CI 中通过相同的 一致性测试样例。Pulse 数据接收服务会重放相同的测试样例——从双方验证契约。

此代码仓库包含 TypeScript 软件包。Swift 和 Kotlin SDK 位于 pulse-sdk-native。

面向 AI Agent

安装：npm i @pulse-circle/web，然后调用 Pulse.init('pk_...') 和 Pulse.track('event', {...})。该软件包独立完整（零依赖，内置默认端点），并随包附带 llms.txt。安装只需 npm；事件会在运行时由最终用户的浏览器发送。

软件包

软件包	用途	安装
@pulse-circle/web	浏览器／任意 Web 应用	npm i @pulse-circle/web
@pulse-circle/react-native	React Native 和 Expo	npm i @pulse-circle/react-native
@pulse-circle/core	与平台无关的引擎（供上述软件包使用）	npm i @pulse-circle/core
@pulse-circle/mcp	本地（stdio）MCP 服务——为 AI Agent 提供离线设置／连接指南	claude mcp add pulse -- npx -y @pulse-circle/mcp

快速入门（web）

npm install @pulse-circle/web

import { Pulse } from '@pulse-circle/web';

Pulse.init('pk_your_api_key');

// Track product events — the SDK batches, persists, and retries for you.
Pulse.track('subscription_started', { plan: 'pro' });

// Tie events to a user after login.
Pulse.identify('user_42');

// On logout, start a fresh anonymous identity.
Pulse.reset();

这就是完整的 API。请参阅各软件包的 README，了解特定平台的安装方法（script 标签、Expo 等）和完整参考。

无处不在的 API

五种方法在所有四个平台上完全相同，只是采用各语言惯用的语法：

init(apiKey, options?)      // configure once
track(event, properties?)   // queue an event
identify(userId)            // associate the current identity with a user id
reset()                     // logout: new anonymous identity
flush()                     // force-send the queue (tests, critical moments)

我们特意不提供屏幕／页面自动跟踪和收入方法：收入来自服务端连接器，因此每个数值都只有唯一可信来源。

可靠性契约

• 每个事件都会在调用 track 时获得一个 idempotency_key 和一个 timestamp——绝不会等到发送时才生成。重试时两者都会以逐字节完全相同的形式重新发送；服务器的主键也包含这两者，因此不稳定的网络永远不会造成重复事件。
• 队列是持久化的（Web 上使用 localStorage，移动端使用文件），且有序。它可在达到各平台上限前保留事件，即使发生重载、崩溃或离线也不例外；达到上限后，会优先淘汰最早的事件，并发出调试警告，而不会无限增长。
• 重试采用带抖动的指数退避。服务器持续拒绝的批次（“毒批次”）会在尝试 10 次后移到一旁，因此绝不会阻塞其后的所有内容。

规范性细节见 protocol/PROTOCOL.md。

开发

npm install
npm test          # conformance fixtures + unit tests (vitest)
npm run lint
npm run typecheck
npm run build     # tsup builds for every package
npm run size -w @pulse-circle/web   # enforce the 10 KB budget

一致性测试样例

protocol/fixtures 是跨平台行为的事实来源。每个 JSON 文件都描述一个场景（“这些 API 调用会产生这些 HTTP 请求”）；每个 SDK 都会通过共享的 测试样例运行器执行这些测试，服务器也会用真实的数据接收流程重放它们。通过修改测试样例来改变行为，每个平台的 CI 都会告诉你哪些实现不符合契约。

发布

各软件包的版本相互独立。在软件包的 package.json 中更新版本，然后推送一个标签：

core-v0.1.0 | web-v0.1.0 | react-native-v0.1.0

发布工作流会验证标签与 package.json 中的版本一致，运行完整的测试、构建和体积检查，然后通过 provenance 发布到 npm。

许可证

MIT © Pulse Circle Studio