@callimacus/intent

中文文档

2.2.5发布于 2026/11/07TypeScriptES Module近 30 天下载 3836

轻量级浏览器 SDK 用于意向事件(仅客户端).

文档目录26 节

* 安装
使用 npm( 建议)
使用量
高级配置选项
CDN 用法
备选案文1:jsDelivr
备选案文2:unpkg
更多信息
管理同意和地理定位旗帜
建议:类型安全函数(v1.1.0.0+)
迁移到 v 2. 0. 0 (去除 setFlag (中文(简体) )
调试日志和调试面板
除错日志
调试小组(视听事件检查员)
& demo 页面
使用 intent_sid
在不同地点共享一次会议
数据收集和隐私
所收集的数据
内建编辑
数据传输和存储
您的责任: 编辑附加字段
如何编辑自定义字段
编辑示例
最佳做法
遵约说明

有意融合

这个意图跟踪器收集同意的客户端上下文并将事件发送到 卡利马库斯。。。 . 它可以通过npm或直接通过脚本标记来方便地被整合到现代应用中(React,Vite,Next.js等).

原生反应 : @callimacus/intent/native 在应用程序中运行同样的管道—— 见文件/反应-内在.md。。。 .

* 安装

使用 npm( 建议)

从 npm 安装软件包 :

npm install @callimacus/intent

使用量

初始化意图在您的应用程序条目中 :

// 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 函数接受以下选项:

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 包含软件包 <script> 标签 :

备选案文1:jsDelivr

<script src="https://cdn.jsdelivr.net/npm/@callimacus/intent/dist/intent.umd.min.js"></script>

备选案文2:unpkg

<script src="https://unpkg.com/@callimacus/intent/dist/intent.umd.min.js"></script>

装入后从全局访问模块 window.Intent 名称空间 :

<script>
  const { initIntent } = window.Intent;

  initIntent({
    clientId: 'cal-pk-...',
    consent: true,
    geo: false,
  });
</script>

调试日志和调试面板

除错日志

默认情况下,SDK不会输出任何控制台日志来避免对浏览器控制台进行闪烁. 然而,您可以让调试日志查看用于性能分析的时间信息 :

import {initIntent} from '@callimacus/intent';

// Enable debug logging during initialization
initIntent({
  clientId: 'cal-pk-...',
  debug: true,  // Enable debug logs
});

或者在运行时切换调试记录 :

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提供了单独的构建变体,以确保调试面板代码不被运出生产:

构建变量

生产建设(违约) - 排除调试面板

npm install @callimacus/intent

import {initIntent} from '@callimacus/intent';  // Production build

<script src="https://unpkg.com/@callimacus/intent/dist/intent.umd.min.js"></script>

调试构建 - 包括调试面板(仅用于开发/测试)

// ESM - use the /debug export
import {initIntent, setDebugPanel} from '@callimacus/intent/debug';

<!-- UMD - use the .debug variant -->
<script src="https://unpkg.com/@callimacus/intent/dist/intent.debug.umd.min.js"></script>

最佳做法:基于环境的加载

使用您的构建系统加载相应的变体 :

// 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内幕的环境都令人关切

使用量

初始化时启用调试面板 :

import {initIntent} from '@callimacus/intent/debug';  // Use debug build

initIntent({
  clientId: 'cal-pk-...',
  consent: true,
  debugPanel: true,  // Enable visual debug panel
});

运行时切换调试面板 :

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初始化和同意控制
调试面板演示
* 完整的文件和使用说明

要使用测试页 :

构建 SDK :
```
npm run build
```

从寄存器根启动本地网络服务器 :

# Using Python 3
python3 -m http.server 8080

# Or using Node.js http-server
npx http-server -p 8080

打开浏览器并导航到 :

http://localhost:8080/demo/test-demo.html

遵循网页上的指示:
- 初始化 SDK
- 启用调试面板
- 给予同意
- 与要素互动以看到抓获的事件

测试页对于向利害关系方演示SDK,测试新的特性,以及理解SDK如何捕捉和处理不同类型的数据是完美的.

使用 `intent_sid`

使用这些工具从您的应用程序读取或管理会话 cookie :

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 他们中的每一个

initIntent({clientId: 'cal-pk-...', linkDomains: ['site.com', 'site.ai']});

点击链接网站的链接后添加 intent_sid 到链接的 URL。这需要同意访问者离开的现场.
访客所在的站点从地址栏上取出参数,并在征得同意后保留ID. 只有在访问者从另一个链接网站到达时.
这需要离开地点派出一名裁判:a Referrer-Policy: no-referrer 页眉或 rel="noreferrer" 在链接上停止交接.

数据收集和隐私

所收集的数据

在获得同意后,Intent SDK会自动收集以下数据来帮助理解用户行为并改进经验: 用户行为 :

截图:可视化抓取页面取景口,降为JPEG格式以高效传输
HTML 内容: 交互元素的串行 HTML(按钮,链接,输入等)
互动事件: 用户动作包括:
- 点击按钮、链接和交互式元素
- 格式提交 (输入字段输入密钥)
- 页面滚动事件
- 网页焦点/blur活动
- 页面视图活动
会话信息数字 :
- 存储在第一党饼干中的会话ID intent_sid (在表示同意时创建)
- 会话 cookie 最大年龄( 默认: 30天, 可通过 sidMaxAgeSeconds(中文(简体) )
背景资料: 浏览器和设备元数据:
- 用户代理: 浏览器名称、版本和平台
- 语文: 首选语言和接受语言设置
- 时区页:1
- 当地时间: 用户时区中的当前日期和时间
- 屏幕: 分辨率、像素比、可用空间和颜色深度
- 视图端口: 窗口大小和屏幕方向
- 设备能力:CPU核,触控支持,指针类型(粗/细)
- 电池状态: 等级和充电状态(如有)
- 网络连接: 连接类型、速度、 RTT 和数据保存模式( 当可用或从性能计时推断时)
- 业绩时间: 用来推断网络特性
- 在线/离线状态: 浏览器连接状态
- 饼干已启用: 浏览器是否允许 cookie
- 不跟踪( DNT): 浏览器 DNT 设置值
- 参考文件: HTTP 裁判员( 如果有的话)
- PWA 状态: 服务工人的存在和显示模式
- 设备方向/平面: 设备物理方向(如有)
- 地理位置: 纬度和经度(仅在通过 geo: true(中文(简体) )
客户端配置 (存储于本地Storage):
- 客户身份( E)clientId(中文(简体) )
- API 端点 (baseUrl(中文(简体) )
- 可选 IP 地址 (ip(中文(简体) )
- 同意地位intent:consent(中文(简体) )
- 地理位置偏好intent:geo(中文(简体) )
- 调试日志偏好( E)intent:debug(中文(简体) )
- 会话最大年龄设置

内建编辑

SDK这个 自动编辑 下列敏感信息:

密码字段 (单位:千美元)<input type="password">(中文(简体) )
具有敏感自动完整属性的窗体字段 (两者) <input> 财务报告和审定财务报表 <textarea> 要素:
- 名称name, (中文(简体) ), given-name, (中文(简体) ), additional-name, (中文(简体) ), family-name, (中文(简体) ), nickname, (中文(简体) ), username(中文(简体) )
- 电子邮件地址email(中文(简体) )
- 电话号码(tel(中文(简体) )
- 地址:
  - 街道地址(street-address, (中文(简体) ), address-line1, (中文(简体) ), address-line2, (中文(简体) ), address-line3(中文(简体) )
  - 行政级别(address-level1, (中文(简体) ), address-level2, (中文(简体) ), address-level3, (中文(简体) ), address-level4(中文(简体) )
  - 邮政和国家postal-code, (中文(简体) ), country, (中文(简体) ), country-name(中文(简体) )
- 信用卡详情:
  - 纸牌号码和安保cc-number, (中文(简体) ), cc-exp, (中文(简体) ), cc-exp-month, (中文(简体) ), cc-exp-year, (中文(简体) ), cc-csc, (中文(简体) ), cc-type(中文(简体) )
  - 持卡人名称( E)cc-name, (中文(简体) ), cc-given-name, (中文(简体) ), cc-additional-name, (中文(简体) ), cc-family-name(中文(简体) )
- 生日介绍bday, (中文(简体) ), bday-day, (中文(简体) ), bday-month, (中文(简体) ), bday-year(中文(简体) )
- 组织细节organization, (中文(简体) ), organization-title(中文(简体) )
- 其他敏感领域sex, (中文(简体) ), webauthn(中文(简体) )

例外 : 搜索字段( E)<input type="search"> 或元素为 role="searchbox")不进行编辑,即使它们具有敏感的自动完整属性,在被捕获的事件中保留搜索功能.

已编辑的字段被替换为占位符文本, 如 <Password>, (中文(简体) ), <Email>, (中文(简体) ), <Credit card>, (中文(简体) ), <Name>, (中文(简体) ), <Phone>, (中文(简体) ), <Address>等,在HTML内容和截图中都有.

数据传输和存储

数据传送方式:

事件发送到 Callimacus API 端点( 默认 ): https://intent.callimacus.ai/events(中文(简体) )
数据用JSON有效载荷通过HTTPS POST请求传送
SDK使用过 fetch() 与 keepalive 页面卸载时的可靠性
要求中没有包括全权证书credentials: 'omit'(中文(简体) )
客户身份是发送到 x-sl-access-token 标题
会话 ID 在 x-intent-sid 标题

本地存储 :

SDK 在浏览器中存储配置和首选项 localStorage
使用的密钥 : intent:consent, (中文(简体) ), intent:geo, (中文(简体) ), intent:debug, (中文(简体) ), intent:data-client-id, (中文(简体) ), intent:data-base-url, (中文(简体) ), intent:data-ip, (中文(简体) ), intent:data-sid-max-age
本地数据持续到用户或应用程序明确清除为止

饼干:

一级饼干 intent_sid 存储会话标识符
Cookie 属性 : SameSite=Lax, (中文(简体) ), Secure (仅限HTTPS)
默认过期: 30 天( 可通过 sidMaxAgeSeconds(中文(简体) )
同意时创建 Cookie, 取消同意时删除

数据保留:

数据保存政策由Callimacus管理,而不是由客户端的SDK管理
有关服务器侧数据保存的信息,请查看您的 Callimacus 账户设置或联系 Callimacus 支持

您的责任: 编辑附加字段

⚠️ 重要: 虽然SDK为共同敏感领域提供自动编辑, 您负责识别和编辑任何与您的应用程序相关的额外敏感或PII数据。。。 .

SDK无法自动检测出所有敏感信息. 您必须明确标记任何自定义字段、专有数据或应用程序特有的敏感内容,以供编辑.

如何编辑自定义字段

使用 data-intent-redact 属性以标记用于编辑的元素 :

选项 1: 使用默认标签重排

<!-- Element will be masked with a gray placeholder labeled "<Sensitive>" -->
<div data-intent-redact>Sensitive content here</div>
<input type="text" data-intent-redact />

<!-- Or explicitly use "mask" value for "<Redacted>" label -->
<div data-intent-redact="mask">Sensitive content</div>

备选案文2:用自定义标签编辑

<!-- Provide a descriptive label using data-intent-redact-label -->
<div data-intent-redact data-intent-redact-label="Account Balance">$1,234.56</div>
<input type="text" data-intent-redact data-intent-redact-label="Social Security Number" />

自定义标签将显示为 <Account Balance> 或者说 <Social Security Number> 在抓取的截图和 HTML 中.

备选案文3:完全忽略要素

<!-- Element will not appear in screenshots or HTML captures at all -->
<div data-intent-redact="ignore">This won't be captured</div>

编辑示例

<!-- Patient medical record number -->
<input 
  type="text" 
  data-intent-redact 
  data-intent-redact-label="Medical Record Number" 
  placeholder="Enter MRN" 
/>

<!-- Customer account balance -->
<div data-intent-redact data-intent-redact-label="Account Balance">
  Balance: $5,432.10
</div>

<!-- Internal employee ID -->
<span data-intent-redact data-intent-redact-label="Employee ID">
  EMP-123456
</span>

<!-- Proprietary business data -->
<section data-intent-redact data-intent-redact-label="Revenue Dashboard">
  <!-- Entire section will be redacted -->
  Q4 Revenue: $10M
</section>

<!-- Element to completely exclude from tracking -->
<div data-intent-redact="ignore">
  Internal debug information
</div>

最佳做法

审查您的表格: 审计所有窗体字段,并确定哪些字段包含标准字段以外的敏感数据或PII数据(名称、电子邮件、电话等)
标记自定义敏感数据: 应用 data-intent-redact 显示用户特定信息、财务数据、健康信息或专有商业数据的任何要素
使用描述标签: 提供有意义的标签 data-intent-redact-label 帮助你了解在回顾抓获的事件时被编辑的内容
测试您的编辑: 在开始制作前, 测试您的页面, 以确保所有敏感信息被妥善遮蔽
经常审计: 定期审查您对新敏感领域的申请, 随着特性的演进可能需要修改

遵约说明

适当的数据编辑对遵守隐私条例(GDPR、CCPA、HIPAA等)至关重要。虽然SDK提供了编辑工具, 作为整合者,你有责任确保所有适用的敏感数据得到适当编辑 依据您的法律法规要求.

版本与发布记录

@callimacus/intent 共发布 13 个版本，首次发布于 2026/09/29；过去 12 个月发布了 13 个版本。

版本	发布日期	距今
`2.2.5`latest	2026/11/07	2 天前
`2.2.4`	2026/11/03	5 天前
`2.2.3`	2026/11/02	7 天前
`2.2.2`	2026/11/01	8 天前
`2.2.1`	2026/10/28	11 天前
`2.2.0`	2026/10/28	11 天前

关于 @callimacus/intent 的常见问题

@callimacus/intent 是什么？

轻量级浏览器 SDK 用于意向事件(仅客户端).

如何安装 @callimacus/intent？

在项目目录运行 npm install @callimacus/intent，或使用 pnpm add / yarn add / bun add。

@callimacus/intent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@callimacus/intent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@callimacus/intent 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@callimacus/intent 可以商用吗？

@callimacus/intent 使用未声明许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

@callimacus/intent 的下载量有多少？

根据 npm 官方下载统计，@callimacus/intent 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,836 次，日均约 128 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@callimacus/intent 还在维护吗？

最新版本 2.2.5 发布于 2026/11/07（2 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/09/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @callimacus/intent

pnpmpnpm add @callimacus/intent
yarnyarn add @callimacus/intent
bunbun add @callimacus/intent

peer 依赖react >=18可选react-native >=0.72可选

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

3,836

约 3836 次日均 128 次

统计周期 2026/10/09 – 2026/11/07
数据来自 npm 官方下载统计，今天更新

最新版本2.2.5发布于 2 天前

开源许可未声明未声明

包体积1.8 MB12 个文件 · 解压后

运行依赖2 个另有 2 个 peer 依赖

模块格式ES Module无副作用，可 tree-shake

TypeScript自带类型

Node.js>=24.0.0

发布版本13 个近 12 个月 13 个

首次发布2026/09/291 个月前

元数据更新2026/11/07

每一个软件包背后，
都有分享与创造的人。