# @callimacus/intent 中文文档
规范地址：https://npmcn.com/package/%40callimacus/intent/
版本：2\.2\.5
npm 元数据更新时间：2026-11-06T21:53:14.474Z
中文译文更新时间：2026-11-09T00:12:31.644Z
软件包许可：未声明
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40callimacus/intent
原文对照：https://npmcn.com/package/%40callimacus/intent/?lang=original
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：1.8 MB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：2 个
- peer 依赖：react \>=18，react-native \>=0\.72
- 首次发布：2026-09-29T08:40:23.139Z
- 最新版本发布：2026-11-06T21:53:14.314Z
- 近 30 天下载量：3836（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）
## 中文简介
轻量级浏览器 SDK 用于意向事件(仅客户端).
## 安装
```sh
npm install @callimacus/intent
```
也可以使用：`pnpm add @callimacus/intent`、`yarn add @callimacus/intent`、`bun add @callimacus/intent`
## README
# 有意融合
[](https://codecov.io/gh/callimacus/intent-sdk)
这个 **意图** 跟踪器收集同意的客户端上下文并将事件发送到 **卡利马库斯**。 。 。 . 它可以通过npm或直接通过脚本标记来方便地被整合到现代应用中(React,Vite,Next.js等).
**原生反应 :** `@callimacus/intent/native` 在应用程序中运行同样的管道—— 见 [文件/反应-内在.md](https://npmcn.com/package/%40callimacus/intent/docs/react-native.md)。 。 。 .
* * *
## \* 安装
### 使用 npm( 建议)
从 npm 安装软件包 :
```bash
npm install @callimacus/intent
```
* * *
## 使用量
初始化 **意图** 在您的应用程序条目中 :
```ts
// app entry
import { initIntent } from '@callimacus/intent';
initIntent({
clientId: 'cal-pk-...', // your Callimacus Client ID
consent: true, // can be toggled later
geo: true, // can be toggled later
});
```
### 高级配置选项
这个 `initIntent` 函数接受以下选项:
```ts
initIntent({
clientId: 'cal-pk-...', // Required: Your Callimacus Client ID
consent: true, // Optional: Enable/disable tracking (default: false)
geo: false, // Optional: Enable/disable geolocation (default: false)
baseUrl: 'https://...', // Optional: Custom API endpoint (default: 'https://intent.callimacus.ai')
ip: '192.0.2.1', // Optional: Client IP address
sidMaxAgeSeconds: 2592000, // Optional: Session cookie max-age in seconds (default: 30 days = 2592000 seconds)
linkDomains: ['site.com', 'site.ai'], // Optional: Sites that share one session (see below)
debug: false, // Optional: Enable debug logging for timing information (default: false)
debugPanel: false, // Optional: Enable visual debug panel (default: false)
});
```
* * *
## CDN 用法
如果您不愿使用 npm, 请通过 a 包含软件包 `
```
### 备选案文2:unpkg
```html
```
装入后从全局访问模块 `window.Intent` 名称空间 :
```html
```
* * *
## 更多信息
- 无 : [@ callimacus/ intent (英语)](https://www.npmjs.com/package/@callimacus/intent)
- jsDelivr: (英语) [https://www.jsdelivr.com/package/npm/@callimacus/intent 页面存档备份,存于互联网档案馆](https://www.jsdelivr.com/package/npm/@callimacus/intent)
- 宽度 : [https://unpkg.com/@callimacus/intent (中文(简体) )](https://unpkg.com/@callimacus/intent)
* * *
## 管理同意和地理定位旗帜
### 建议:类型安全函数(v1.1.0.0+)
使用专门的帮助器功能来更好的类型安全和IDE支持:
```ts
import {setConsent, setGeo, setDebug} from '@callimacus/intent';
// Grant or revoke consent
setConsent(true); // granted
setConsent(false); // disabled
// Enable or disable device geolocation capture
setGeo(true); // enabled
setGeo(false); // disabled
// Enable or disable debug logging
setDebug(true); // enabled
setDebug(false); // disabled
```
**类型安全功能的好处:**
- 清除自文档 API
- 更好的 IDE 自动完成和类型检查
- 防止旗下名称中的打字
- 明确的仅布尔参数
* * *
**行为:**
- 当获得同意时,追踪器会保留第一当事方饼干 `intent_sid`。 。 。 .
- 如果取消同意, 跟踪器会清除 `intent_sid` 并停止发送事件.
### 迁移到 v 2. 0. 0 (去除 `setFlag`(中文(简体) )
**中断更改 :** 常规 `setFlag` 函数在 **页:1**。不再出口。 将每个呼叫替换为类型安全等同:
```ts
// ❌ Removed in v2.0.0
setFlag('intent:consent', true);
setFlag('intent:geo', false);
setFlag('intent:debug', true);
// ✅ Use the type-safe functions
setConsent(true); // replaces setFlag('intent:consent', ...)
setGeo(false); // replaces setFlag('intent:geo', ...)
setDebug(true); // replaces setFlag('intent:debug', ...)
```
**移徙步骤:**
1. 寻找所有用途 `setFlag` 在您的代码库中( e)`grep -r "setFlag" your-codebase/`) (中文(简体) ).
2. 替换每个呼叫 :
- `setFlag('intent:consent', ...)` → `setConsent(...)`
- `setFlag('intent:geo', ...)` → `setGeo(...)`
- `setFlag('intent:debug', ...)` → `setDebug(...)`
3. 如果你依赖 `setFlag` 带有自定义旗名,打开一个问题来讨论您的使用案例——现在公众API只支持上面的三面旗.
* * *
## 调试日志和调试面板
### 除错日志
默认情况下,SDK不会输出任何控制台日志来避免对浏览器控制台进行闪烁. 然而,您可以让调试日志查看用于性能分析的时间信息 :
```ts
import {initIntent} from '@callimacus/intent';
// Enable debug logging during initialization
initIntent({
clientId: 'cal-pk-...',
debug: true, // Enable debug logs
});
```
或者在运行时切换调试记录 :
```ts
import {setDebug} from '@callimacus/intent';
// Enable debug logging (recommended - type-safe)
setDebug(true);
// Disable debug logging
setDebug(false);
```
启用调试日志后, SDK 将向控制台输出计时信息, 包括:
- **HTML 序列化时间**: 将 DOM 序列化到 HTML 所需的时间
- **截图抓取时间**: html2canvas-pro制作页面的时间
- **JPEG 编码时间**: 将画布编码到 JPEG 格式所需的时间
- **总捕获时间**:整个捕捉过程的总时间
这对于:
- **性能调谐**:查明捕捉过程中的瓶颈
- **开发调试**: 在开发过程中理解 SDK 行为
- **生产故障**: 临时使日志能够诊断问题
**说明:** 调试日志默认被禁用,以防止生产中的控制台垃圾邮件. 只有在调试或性能分析需要时才能启用.
### 调试小组(视听事件检查员)
> **QQ 警告:调试面板仅用于开发与调试.**
> **在生产环境中不要启用.** 它暴露出内部SDK行为,包括截图,事件有效载荷,以及HTML内容,可能揭示出敏感的应用结构.
SDK提供了单独的构建变体,以确保调试面板代码不被运出生产:
#### 构建变量
**生产建设(违约)** - 排除调试面板
```bash
npm install @callimacus/intent
```
```ts
import {initIntent} from '@callimacus/intent'; // Production build
```
```html
```
**调试构建** - 包括调试面板(仅用于开发/测试)
```ts
// ESM - use the /debug export
import {initIntent, setDebugPanel} from '@callimacus/intent/debug';
```
```html
```
#### 最佳做法:基于环境的加载
使用您的构建系统加载相应的变体 :
```ts
// Vite / Webpack example
const Intent = import.meta.env.PROD
? await import('@callimacus/intent')
: await import('@callimacus/intent/debug');
Intent.initIntent({
clientId: 'cal-pk-...',
consent: true,
debugPanel: !import.meta.env.PROD // Only in development
});
```
**建议使用实例 :**
- **地方发展**: 集成过程中调试事件抓取
- **测试环境**: 验证测试/测试中的 SDK 行为
- **内部演示**: 向内部利益攸关方显示大小写 SDK 功能
- **解决问题**:非生产环境中的诊断问题
**不建议:**
- 生产网站或应用程序
- QQ 最终用户可访问的公共演示
- \* 任何暴露SDK内幕的环境都令人关切
#### 使用量
**初始化时启用调试面板 :**
```ts
import {initIntent} from '@callimacus/intent/debug'; // Use debug build
initIntent({
clientId: 'cal-pk-...',
consent: true,
debugPanel: true, // Enable visual debug panel
});
```
**运行时切换调试面板 :**
```ts
import {setDebugPanel} from '@callimacus/intent/debug';
// Show debug panel (development only)
setDebugPanel(true);
// Hide debug panel
setDebugPanel(false);
```
**调试面板特性 :**
- 📸 **截图**: 查看SDK拍摄的 JPEG 截图
- 🔍 **事件详情**: 扩展每个事件以查看属性、 HTML 和边框数据
- 🎯 **事件类型**: 查看所捕获的事件类型(单击、页面视图、滚动等)
- 🕐 **时间戳**: 每个事件发生时的音轨
- 🗑️ **清除事件**: 单击单个按钮清除事件日志
- 🎨 **可拖动**: 移动屏幕上的面板
- ➖ **最小化**: 不需要时折叠面板
调试面板作为浮出水面的窗口出现在右上角,可以在页面上的任何位置被拖取. 它显示多达50起最近的事件(在达到极限时自动去掉最老的事件).
* * *
## & demo 页面
综合测试和演示页面载于 `demo/test-demo.html` 文档。 此页面显示:
- QQ 所有窗体输入类型(文本、电子邮件、密码、日期、颜色、范围等)
- QQ 交互式元素( 按钮、 链接、 可点击的 divs)
- • 自动编辑字段(电子邮件、密码、电话、信用卡等)
- 自定义编辑示例 `data-intent-redact`
- SDK初始化和同意控制
- 调试面板演示
- \* 完整的文件和使用说明
**要使用测试页 :**
1. 构建 SDK :
```bash
npm run build
```
2. 从寄存器根启动本地网络服务器 :
```bash
# Using Python 3
python3 -m http.server 8080
# Or using Node.js http-server
npx http-server -p 8080
```
3. 打开浏览器并导航到 :
```
http://localhost:8080/demo/test-demo.html
```
4. 遵循网页上的指示:
- 初始化 SDK
- 启用调试面板
- 给予同意
- 与要素互动以看到抓获的事件
测试页对于向利害关系方演示SDK,测试新的特性,以及理解SDK如何捕捉和处理不同类型的数据是完美的.
* * *
## 使用 `intent_sid`
使用这些工具从您的应用程序读取或管理会话 cookie :
```ts
import {
getIntentSessionId,
clearIntentSessionId,
ensureIntentSessionId,
setIntentSessionMaxAge,
} from '@callimacus/intent';
const sid = getIntentSessionId(); // string | undefined, can be sent to backend
clearIntentSessionId(); // deletes cookie
ensureIntentSessionId(); // creates cookie if missing
setIntentSessionMaxAge(86400); // updates cookie max-age (in seconds)
```
### 在不同地点共享一次会议
`intent_sid` 是一个第一党饼干,所以每个站点(和每个子域)都有自己的. 当访客在您的站点之间移动时, 例如从 `site.com` 改为 `site.ai` 或从 `www.site.com` 改为 `shop.site.com`,通过同样的 `linkDomains` 他们中的每一个
```ts
initIntent({clientId: 'cal-pk-...', linkDomains: ['site.com', 'site.ai']});
```
- 点击链接网站的链接后添加 `intent_sid` 到链接的 URL。 这需要同意访问者离开的现场.
- 访客所在的站点从地址栏上取出参数,并在征得同意后保留ID. 只有在访问者从另一个链接网站到达时.
- 这需要离开地点派出一名裁判:a `Referrer-Policy: no-referrer` 页眉或 `rel="noreferrer"` 在链接上停止交接.
* * *
## 数据收集和隐私
### 所收集的数据
在获得同意后,Intent SDK会自动收集以下数据来帮助理解用户行为并改进经验: 用户行为 :
1. **截图**:可视化抓取页面取景口,降为JPEG格式以高效传输
2. **HTML 内容**: 交互元素的串行 HTML(按钮,链接,输入等)
3. **互动事件**: 用户动作包括:
- 点击按钮、链接和交互式元素
- 格式提交 (输入字段输入密钥)
- 页面滚动事件
- 网页焦点/blur活动
- 页面视图活动
4. **会话信息**数字 :
- 存储在第一党饼干中的会话ID `intent_sid` (在表示同意时创建)
- 会话 cookie 最大年龄( 默认: 30天, 可通过 `sidMaxAgeSeconds`(中文(简体) )
5. **背景资料**: 浏览器和设备元数据:
- **用户代理**: 浏览器名称、版本和平台
- **语文**: 首选语言和接受语言设置
- **时区**页:1
- **当地时间**: 用户时区中的当前日期和时间
- **屏幕**: 分辨率、像素比、可用空间和颜色深度
- **视图端口**: 窗口大小和屏幕方向
- **设备能力**:CPU核,触控支持,指针类型(粗/细)
- **电池状态**: 等级和充电状态(如有)
- **网络连接**: 连接类型、 速度、 RTT 和数据保存模式( 当可用或从性能计时推断时)
- **业绩时间**: 用来推断网络特性
- **在线/离线状态**: 浏览器连接状态
- **饼干已启用**: 浏览器是否允许 cookie
- **不跟踪( DNT)**: 浏览器 DNT 设置值
- **参考文件**: HTTP 裁判员( 如果有的话)
- **PWA 状态**: 服务工人的存在和显示模式
- **设备方向/平面**: 设备物理方向(如有)
- **地理位置**: 纬度和经度(仅在通过 `geo: true`(中文(简体) )
6. **客户端配置** (存储于本地Storage):
- 客户身份( E)`clientId`(中文(简体) )
- API 端点 (`baseUrl`(中文(简体) )
- 可选 IP 地址 (`ip`(中文(简体) )
- 同意地位`intent:consent`(中文(简体) )
- 地理位置偏好`intent:geo`(中文(简体) )
- 调试日志偏好( E)`intent:debug`(中文(简体) )
- 会话最大年龄设置
### 内建编辑
SDK这个 **自动编辑** 下列敏感信息:
- **密码字段** (单位:千美元)``(中文(简体) )
- **具有敏感自动完整属性的窗体字段** (两者) `` 财务报告和审定财务报表 `