);
}
```
下面是一个简单的例子,说明在发出命令时进行核查的组件:
```tsx
import { useDodgeball } from "@dodgeball/trust-sdk-client";
import { useState, useEffect } from "react";
import axios from "axios";
export default function MyComponent() {
const dodgeball = useDodgeball(); // Once initialized, you can omit the public API key
const [isPlacingOrder, setIsPlacingOrder] = useState(false);
const [isOrderPlaced, setIsOrderPlaced] = useState(false);
const [isOrderDenied, setIsOrderDenied] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
setIsPlacingOrder(false);
}, [isOrderPlaced, isOrderDenied])
const placeOrder = async (order, previousVerification = null) => {
const sourceToken = await dodgeball.getSourceToken();
const endpointResponse = await axios.post("/api/orders", { order }, {
headers: {
"x-dodgeball-source-token": sourceToken, // Pass the source token to your API
"x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
}
});
dodgeball.handleVerification(endpointResponse.data.verification, {
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, simply pass the verification ID in to your API
await placeOrder(order, verification.id);
},
onApproved: async () => {
// If no additional check was required, update the view to show that the order was placed
setIsOrderPlaced(true);
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
setIsOrderDenied(true);
},
onError: async (error) => {
// If there was an error performing the verification, display it
setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
setIsPlacingOrder(false);
}
});
}
const onPlaceOrderClick = async () => {
setIsPlacingOrder(true);
const order = {} // Fill in with whatever data your API expects
await placeOrder(order);
}
return (
My Component
This component is using the Dodgeball Client SDK.
{isOrderPlaced ? (
Your order was placed!
) : (
{isOrderDenied && Order was denied. Contact support.}
{error &&
{error}
}
)}
);
}
```
### 非反应应用程序
道奇球客户端 SDK 输出 a `Dodgeball` 类,可以传递公共 API 密钥和可选配置对象。 见 [构造器](https://npmcn.com/package/%40dodgeball/trust-sdk-client/#readme-constructor) 章节,以获取关于配置的更多信息。 您可以在网站上找到您的公共 API 密钥 [开发者设置](https://app.dodgeballhq.com/developer) 页 次.
您首先需要用您的公共 API 密钥初始化 SDK, 可在 [开发者设置](https://app.dodgeballhq.com/developer) 页 次 只需在SDK首次装入时进行一次,如下例所示:
```js
import { Dodgeball } from "@dodgeball/trust-sdk-client";
const dodgeball = new Dodgeball('public-api-key...'); // Do this once when your application first loads
const sourceToken = await dodgeball.getSourceToken();
```
当您知道当前登录用户的身份时,请拨 `dodgeball.track()`。 。 。 .
```js
// As soon as you have a session ID, pass it to dodgeball.track()
const onSession = (currentSession) => {
dodgeball.track(currentSession?.id);
}
// When you know the ID of the currently logged-in user, pass it along with a session ID to dodgeball.track()
const onLogin = (currentSession, currentUser) => {
dodgeball.track(currentSession?.id, currentUser?.id);
}
```
稍后,当你想核实一个访客被允许执行某项行动时,请打电话 `dodgeball.getSourceToken()` 以获得代表此设备的标志。 传回 `sourceToken` 给你的API。 一旦你的API返回回复,通过 `verification` 改为 `dodgeball.handleVerification` 以及一些回调功能:
```js
const placeOrder = async (order, previousVerificationId = null) => {
const sourceToken = await dodgeball.getSourceToken();
const endpointResponse = await axios.post("/api/orders", { order }, {
headers: {
"x-dodgeball-source-token": sourceToken, // Pass the source token to your API
"x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
}
});
dodgeball.handleVerification(endpointResponse.data.verification, {
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, simply pass the verification ID in to your API
await placeOrder(order, verification.id);
},
onApproved: async () => {
// If no additional check was required, update the view to show that the order was placed
setIsOrderPlaced(true);
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
setIsOrderDenied(true);
},
onError: async (error) => {
// If there was an error performing the verification, display it
setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
setIsPlacingOrder(false);
}
});
}
```
### 通过 CDN 装入
Dodgeball客户端 SDK 也可以通过 CDN 在这个url 获取:
```
https://www.unpkg.com/@dodgeball/trust-sdk-client@latest/dist/umd/index.js
```
要装入 HTML 文档 :
```html
My Application
Your application's content...
```
## API 密码
### 配置
* * *
软件包需要公开的 API 密钥作为构建器的第一个参数.
```js
const dodgeball = new Dodgeball("public-api-key...");
```
可选的,您可以在多个配置选项中传递到构建器:
```js
const dodgeball = new Dodgeball("public-api-key...", {
// Optional configuration
apiVersion: "v1",
apiUrl: "https://api.dodgeballhq.com",
logLevel: "ERROR",
disableCookies: false,
isEnabled: true
});
```
| 选项 | 默认 | 说明 |
| :-- | :-- | :-- |
| `apiVersion` | `v1` | 要使用的道奇球API版本. |
| `apiUrl` | `https://api.dodgeballhq.com` | Dodgeball API的基址. 用于向不同环境发送请求,例如 `https://api.sandbox.dodgeballhq.com`。 。 。 . |
| `logLevel` | `INFO` | 要使用的伐木水平 。 可能的备选办法是: `TRACE`, (中文(简体) ), `INFO`, (中文(简体) ), `ERROR`,或 `NONE`。 。 。 . `TRACE` 财务报告和审定财务报表 `INFO` 用于调试. `ERROR` 只记录出错. `NONE` 关闭所有伐木. |
| `disableCookies` | `false` | 若为 `true`,SDK将不会使用cookie来存储源代码. |
| `isEnabled` | `true` | 若为 `false`SDK不会给外部API打电话 这对于地方发展是有用的. |
### 跟踪用户
这个 `track` 方法用于初始化已知的任何会话和用户信息。 此方法应在您有会话ID和可选用户ID后立即调用. 如果没有用户ID,可以通过 `null` 或省略第二个论据.
```js
dodgeball.track(sessionId, userId);
```
| 参数 | 类型 | 说明 |
| :-- | :-- | :-- |
| `sessionId` | `string` | 本届会议的编号。 这可能是任何代表用户在系统中活动的独特字符串 。 如果没有会话ID可用,请通过 `sourceToken` 从 `dodgeball.getSourceToken()`。 。 。 . |
| `userId` | `string` | 当前用户的ID . |
### 获取源选项
这个 `getSourceToken` 方法返回表示当前设备上活动期间的符号。 当您想要验证一个用户被允许执行动作时, 此符号应该传递到您的 API 。 源代码在1小时后过期,由SDK自动刷新.
```js
const sourceToken = await dodgeball.getSourceToken();
```
如果Aync/Await不是你的东西, 你可以引用 `getSourceToken` 将调用源代码作为参数的调用函数:
```js
dodgeball.getSourceToken((sourceToken) => {});
```
### 刷新源代码
这个 `refreshSourceToken` 方法刷新当前源代码。 如果您想要在符号过期前刷新该符号, 如用户登录退出时, 此选项将有所帮助 .
```js
const newSourceToken = await dodgeball.refreshSourceToken();
```
或者,你可以援引 `refreshSourceToken` 用新源符号调用回调函数作为参数的方法:
```js
dodgeball.refreshSourceToken((newSourceToken) => {});
```
### 处理核查
这个 `handleVerification` 用于处理来自您的 API 的校验响应。 此方法应在您的 API 返回包含验证对象的响应后调用 。 核查对象载有关于已进行的核查的资料。 这个 `handleVerification` 方法取一个核查对象和一个包含若干回调函数的配置对象。 这个 `handleVerification` 方法将根据核查反应调用适当的回调功能.
```js
dodgeball.handleVerification(
verification, // This is the verification object returned from your API
{
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, the requested action has not yet been taken on your API. To do so, simply retry the request, being sure to pass the verification.id to your API. On your API the verification.id should be passed as the useVerificationId argument to dodgeball.checkpoint()
},
onApproved: async () => {
// If no additional check was required, the requested action was approved and taken on your API, so you should update the view to show that the action was taken
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
},
onPending: async (verification) => {
// (Optional) This callback will be called if the verification is still processing. This is useful to inform the user that their request is still being processed.
},
onBlocked: async (verification) => {
// (Optional) This callback will be called if the verification requires additional information from the user before it can be processed (e.g. the user needs to complete an MFA challenge or IDV flow)
},
onError: async (verificationError) => {
// (Optional) If there was an error performing the verification, this callback will be called with an error object. If the user cancels the verification, error.errorType = "CANCELLED"
}
},
{
// Optional configuration
maxDuration: 24 * 60 * 60 * 1000, // 24 hours
}
);
```
| 参数 | 类型 | 说明 |
| :-- | :-- | :-- |
| `verification` | `object` | 从您的 API 返回的校验对象 . |
| `context` | `object` | 包含上述几种召回函数的对象. |
| `config` | `object` | 包含多个配置选项的对象 . |
| `config.maxDuration` | `number` | 等待核查完成的最长时间。 如果核查工作在这一段时间之后仍未完成,则 `onError` 以错误对象调用调用. |
## 常见问题
### @dodgeball/trust-sdk-client 是什么？
道奇球客户端 SDK
### 如何安装 @dodgeball/trust-sdk-client？
在项目目录运行 npm install @dodgeball/trust-sdk-client，或使用 pnpm add / yarn add / bun add。
### @dodgeball/trust-sdk-client 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @dodgeball/trust-sdk-client 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @dodgeball/trust-sdk-client 可以商用吗？
@dodgeball/trust-sdk-client 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @dodgeball/trust-sdk-client 的下载量有多少？
根据 npm 官方下载统计，@dodgeball/trust-sdk-client 在 2026/10/13 – 2026/11/11 这 30 天内被下载 8,154 次，日均约 272 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @dodgeball/trust-sdk-client 还在维护吗？
最新版本 0\.0\.40 发布于 2025/05/02（1\.5 年前）；至今共发布 39 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/12/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。