# @castleio/castle-js 中文文档

规范地址：https://npmcn.com/package/%40castleio/castle-js/

版本：2\.8\.5
npm 元数据更新时间：2026-11-05T08:49:50.959Z
中文译文更新时间：2026-11-09T04:17:30.454Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40castleio/castle-js
原文对照：https://npmcn.com/package/%40castleio/castle-js/?lang=original
项目主页：https://castle.io/

弃用说明：Castle\.js v2 is deprecated\. Please upgrade to v3 — upgrade notes are available in the Castle dashboard\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2021-06-14T21:08:12.439Z
- 最新版本发布：2026-06-25T21:55:37.364Z
- 近 30 天下载量：1364116（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 4 个）

## 中文简介

城堡指纹脚本

## 安装

```sh
npm install @castleio/castle-js
```

也可以使用：`pnpm add @castleio/castle-js`、`yarn add @castleio/castle-js`、`bun add @castleio/castle-js`

## README

# 城堡指纹脚本

包装版本 [城堡](https://castle.io/) 指纹脚本.

## 导言

Castle JavaScript 自动抓取您网页应用程序中的每个用户动作,包括点击,自带,刷新,格式提交,以及页面浏览等. 我们利用这些数据来构建良好用户行为的剖面图,以便检测坏处.

## 安装

```bash
npm install --save @castleio/castle-js

```

```bash
yarn add @castleio/castle-js

```

## 配置

### 应用程序的基本配置

```js
// @option options [string] :pk castle publishable key.
// @option options [object] :window (default `window`) eg JSDOM.window
// @option options [string] :apiUrl (default `https://m.castle.io/v1/monitor`) castle api url
// @option options [number] :timeout (default 1000) castle api response timeout
// @option options [boolean] :verbose (default true) verbose mode (console warnings)
// @option options [object] :storage (default name `__cuid`, default expireIn 400 days in seconds: `34560000`) used for storing uuid in the localStorage and the cookies, and for setting cookie expiration time.

import * as Castle from '@castleio/castle-js'

Castle.configure(options);
```

### 浏览器版本( 遗留设置)

如果您的环境不支持模块, 您可以使用浏览器版本

```js
import '@castleio/castle-js/dist/castle.browser.js'

Castle.configure(options);
```

## 使用量

### 获取城堡请求令牌

```js
import * as Castle from '@castleio/castle-js'

Castle.createRequestToken().then( (requestToken) => {
  ....
});

// or
const requestToken = await Castle.createRequestToken();

```

见 [城堡医生](https://docs.castle.io/v1/tutorials/client-side-integration/web/#npm-package) 需要更多信息和如何进一步传递信号.

### 窗体提交帮助示例( 当使用 cdn 版本时)

```js
// @param event [Event] submit event
// @param onDone [Function] optional form submit callback replacement
```

```html
<form action="/" onsubmit="Castle.injectTokenOnSubmit(event)">
  <button type="submit">Submit</button>
</form>
```

也可以直接获得帮助(在使用castle.umd.js时)

```js
import * as Castle from '@castleio/castle-js'

const submitHandler = (evt) => Castle.injectTokenOnSubmit(evt);
```

```html
<form action="/" onsubmit="submitHandler(event)">
  <button type="submit">Submit</button>
</form>
```

### 发送页面事件

```js
// @param options [PageParams] castle page command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] optiona jwt encoded UserParams
// @option name [String]
// @option referrer [String]
// @option url [String]

import * as Castle from '@castleio/castle-js'

const page = Castle.page(options);

```

事件响应可以以呼叫等承诺来验证.

```js
import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (300ms)

Castle.page(options).then( (result) => { } )
```

### 发送窗体事件

```js
// @param options [FormParams] castle form command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option values [Record<string, string>]

import * as Castle from '@castleio/castle-js'

Castle.form(options);

```

事件响应可以以呼叫等承诺来验证.

```js
import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or throttled event (300ms)

Castle.form(options).then( (result) => { } )
```

## 窗体为窗体事件提交帮助

```js
import * as Castle from '@castleio/castle-js'

const user = YOUR_USER_DATA;
const submitHandler = (evt) => Castle.formEventOnSubmit(evt, user);
```

```html
<form action="/" data-castle-name="Change Profile" onsubmit="submitHandler(event)">
  <input type="text" name="user_mail" data-castle-value="email">
  <button type="submit">Submit</button>
</form>
```

### 发送自定义事件

```js
// @param options [CustomParams] castle custom command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option properties [Record<string,string>]

import * as Castle from '@castleio/castle-js'

const custom = Castle.custom(options);

```

事件响应可以以呼叫等承诺来验证.

```js
import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (default 1000ms)

Castle.custom(options).then( (result) => { } )
```

# 中断更改

## 从1.x升级到2.0.x

### 1.x 运算

遗产包 : [https://www.npmjs.com/package/castle.js (中文(简体) )](https://www.npmjs.com/package/castle.js)

```js
require "castle.js"
```

```js
_castle('setAppId', "YOUR_APP_ID")
_castle('getClientId')
```

### 2.0.x (中文(简体) )

新建软件包 :

```js
import * as Castle from "@castleio/castle-js"
```

1.  重命名对象从 `_castle` 改为 `Castle` 在新模块中,但保留 `_castle` 在CDN版本以及浏览器专用模块中 `@castleio/castle-js/dist/castle.browser.js`
2.  引入了请求符的概念,每个呼叫需要生成到卡塞尔的服务器侧API.

```js
Castle.createRequestToken().then( (requestToken) => {
});

// or

const token = await Castle.createRequestToken();
```

3.  请求符已经无法从 cookie 字符串中取出 .
4.  取消了以下所有方法:

`autoForwardClientId`, (中文(简体) ), `autoTrack`, (中文(简体) ), `catchHistoryErrors`, (中文(简体) ), `identify`, (中文(简体) ), `setUserId`, (中文(简体) ), `setAccount`, (中文(简体) ), `setKey`, (中文(简体) ), `setAccount`, (中文(简体) ), `sessionId`, (中文(简体) ), `reset`, (中文(简体) ), `page`, (中文(简体) ), `trackPageView`, (中文(简体) ), `setTrackerUrl`

请求 Token现在需要在请求中被通过,它已经无法在饼干中使用。 检查 [文档](https://docs.castle.io/docs/sdk-browser)

## 从2.0.x升级到2.1.x或稍后

### 2.0.x (中文(简体) )

```js
Castle.configure(YOUR_CASTLE_APP_ID);
```

### 2.1.x 或晚点

1.  已删除 `_castle` 所有版本的对象, 现在只依赖 `Castle`。 。 。 .
    
2.  切换到使用 **可出版密钥** 与现在已贬值的 App ID 相同.
    

```js
Castle.configure({pk: YOUR_PUBLISHABLE_KEY});
```

3.  `onFormSubmit` 已更名为 `injectTokenOnSubmit`
    
4.  `_castle` 全球方法不再支持,已被替换为 `Castle` (用于CDN和castle.browser.js版本)检查 [文档](https://docs.castle.io/docs/sdk-browser)
    
5.  CDN版本不再需要 `appID` 在url和需要时
    

```javascript
<script>Castle.configure({pk: YOUR_CASTLE_PUBLISHABLE_KEY});</script>
```

待补。 CDN版本不能用于生成请求符,而只能用于跟踪客户端-侧事件.

6.  介绍 `page`, (中文(简体) ), `form`,以及 `custom` 客户端事件跟踪方法

更多信息可在 [文档](https://docs.castle.io/docs/sdk-browser#breaking-changes)

## 更改日志

-   2.8.5 - 固定状态 `types` 选项
-   2.8.4 - 最新业绩
-   2.8.3 - 最新业绩
-   2.8.2 - 加强安全保障
-   2.8.1 - 错误修正
-   2.8.0 - 安全更新,取消对旧浏览器的官方支持(目标从ES3更新为ES5);更新最低要求
-   2.7.1 - 无变化
-   2.7.0 - 国家 `createRequestToken`, (中文(简体) ), `page`, (中文(简体) ), `form`,以及 `custom` 返回承诺(如果有的话),内部增强
-   2.6.2 - 缩小捆绑尺寸、增加内部特性、增加链条支持 `.then`,以及使用 `.catch` 财务报告和审定财务报表 `.finally` 用于创建 RequestToken、页面、窗体和自定义
-   2.6.1 - 无证件 `getVersion` 函数和临时饼干的减少使用,内部增强
-   2.6.0 - 错误修正和内部特性
-   2.5.3 - 安全最新情况
-   2.5.2 - 内部释放
-   2.5.1 - 扩展浏览器支持范围和错误修正
-   2.5.0 - 提高机器人检测能力,改进性能,修复错误
-   2.4.3 - 内部增强
-   2.4.2 - 强制 https 显示器请求、错误修正、 utf 增强
-   2.4.1 内部加强
-   2.4.0 - 更大的一组增强和内部特性
-   2.3.6 - 内部增强
-   2.3.5 — d.ts 文件中含有导出类型的固定问题
-   2.3.4 - 内部增强
-   2.3.3-内部增强
-   2.3.2 - 错误修正
-   2.3.1 - 内部稳定
-   2.3.0 - 新的配置选项 `throttling`,默认启用,并设置为500ms,用于在短时间内发送多个自定义事件.
-   2.2.0 - 新的配置选项 `storage`,已贬值 `storageNamespace`和稳定改善.
-   2.1.15 - 新的配置选项 `storageNamespace`,用于指定本地Storage和cookie存储命名空间,稳定性改进
-   2.1.14. 改善稳定性
-   2.1.13 - 未配置 pk 时抛出错误
-   2.1.12 – 使 Castle.confile 返回 Castle 界面对象
-   2.1.11 - 为用户添加页面、格式、自定义事件的地址支持
-   2.1.10 - 错误修正和稳定性改进
-   2.1.9 - 错误修正和稳定性改进
-   2.1.8 - pk验证和内部增强
-   2.1.7 - 页面命令错误修正和改进
-   2.1.6 - 固定的JWT验证问题
-   2.1.5 - 读取更新
-   2.1.4 - 改善稳定性
-   2.1.3 - 视图事件错误修正和稳定性改进
-   2.1.2 - 视图事件错误修正
-   2.1.1 - 内部增强和稳定性改进
-   2.1.0 — 添加页面、 窗体、 自定义事件支持、 更改配置 DSL、 添加窗体EventOnSubmit 帮助器、 在FormSubmit上更名以注入TokenOnSubmit( 突破更改 - 检查) [文档](https://docs.castle.io/docs/sdk-browser) (中文(简体) )
-   2.0.4 - 错误修正
-   2.0.3 - 错误修正和稳定性改进
-   2.0.2 - 错误修正
-   2.0.1 - 内部增强
-   2.0.0 - 从 [1.x 运算](https://www.npmjs.com/package/castle.js),模块化,更新DSL,(突破更改 - 检查) [文档](https://docs.castle.io/docs/sdk-browser) (中文(简体) )

## 最低要求:

-   铬 38+
-   Firefox 44+ (英语)
-   歌剧院 32+
-   边缘12+
-   萨法里8+
-   所有现代浏览器(桌面和移动)

## 许可证

麻省理工学院

## 常见问题

### @castleio/castle-js 是什么？

城堡指纹脚本注意：该包已被作者标记为弃用——Castle\.js v2 is deprecated\. Please upgrade to v3 — upgrade notes are available in the Castle dashboard\.

### 如何安装 @castleio/castle-js？

在项目目录运行 npm install @castleio/castle-js，或使用 pnpm add / yarn add / bun add。

### @castleio/castle-js 支持 TypeScript 吗？

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

### @castleio/castle-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @castleio/castle-js 可以商用吗？

@castleio/castle-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @castleio/castle-js 的下载量有多少？

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

### @castleio/castle-js 还在维护吗？

最新版本 2\.8\.5 发布于 2026/06/26（4 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 4 个；首次发布于 2021/06/15。作者已将其标记为弃用，新项目建议寻找替代方案。