# @bluprynt/kyi-widget-sdk 中文文档

规范地址：https://npmcn.com/package/%40bluprynt/kyi-widget-sdk/

版本：0\.1\.1
npm 元数据更新时间：2026-08-21T09:39:06.048Z
中文译文更新时间：2026-11-08T09:04:19.751Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bluprynt/kyi-widget-sdk
原文对照：https://npmcn.com/package/%40bluprynt/kyi-widget-sdk/?lang=original
项目主页：https://github.com/bluprynt/kyi-widget-sdk#readme
源码仓库：https://github.com/bluprynt/kyi-widget-sdk

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

- 包体积（解压后）：155 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-03-20T08:50:07.254Z
- 最新版本发布：2026-03-31T07:49:41.330Z
- 近 30 天下载量：23600（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Bluprynt KYI 部件 SDK - 在应用程序中嵌入“ 知道你的发行人” 验证

## 安装

```sh
npm install @bluprynt/kyi-widget-sdk
```

也可以使用：`pnpm add @bluprynt/kyi-widget-sdk`、`yarn add @bluprynt/kyi-widget-sdk`、`bun add @bluprynt/kyi-widget-sdk`

## README

# 模糊 KYI 部件 SDK

[![SOC 2 Type 1](https://img.shields.io/badge/SOC%202-Type%201-blue)](https://bluprynt.com/) [![npm version](https://img.shields.io/npm/v/@bluprynt/kyi-widget-sdk)](https://www.npmjs.com/package/@bluprynt/kyi-widget-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

将 Bluprynt 的 KYI( 了解您的发行人) 校验部件嵌入您的网络应用程序 .

## 安装

```bash
npm install @bluprynt/kyi-widget-sdk
```

```bash
yarn add @bluprynt/kyi-widget-sdk
```

```bash
pnpm add @bluprynt/kyi-widget-sdk
```

## KYI 部件 SDK 如何工作

1.  向 Bluprynt 询问 `SECRET_KEY` 作为伙伴融合的一部分.
2.  在您的后端执行 Access Token JWT 生成 .
3.  使用 KYI 部件 SDK 并代表您的用户生成 Access Token .

使用 [游乐场](https://blupryntco.github.io/kyi-widget-sdk) 测试 KYI 部件 SDK.

## 快速启动

### 1\. 生成访问托肯(服务器侧)

如果您在后端使用Node.js, 请随意使用此软件包生成符号 :

```typescript
// server.ts (Node.js)
import { generateToken } from "@bluprynt/kyi-widget-sdk/server";

const accessToken = await generateToken({
  issuer: "your-partner-id",
  secretKey: process.env.BLUPRYNT_SECRET_KEY!,
  userId: "user-123", // Your internal user identifier
  expiresIn: 3600, // Optional: token expiry in seconds (default: 1 hour)
});

// Return token to your frontend
res.json({ accessToken });
```

使用其他平台而不是Node.js是正常的,但是你需要自己生成JWT,并用它签名 `SECRET_KEY` 你从布鲁普林特那里得到的 注意信使的有效载荷必须遵循结构:

```json
{
  "sub": "user-123",
  "iss": "your-partner-id",
  "iat": 1766146154,
  "exp": 1766149754
}
```

### 2\. 嵌入部件( 外侧)

使用访问令牌嵌入 KYI 部件 :

```typescript
// client.ts (Browser)
import { kyi } from "@bluprynt/kyi-widget-sdk";

// Fetch token from your backend
const { accessToken } = await fetch("/api/kyi-token").then((r) => r.json());

// Embed the widget
const widget = kyi("modal", "kyi", accessToken, {
  onClose: () => {
    console.log("Widget closed");
  },
  onError: (error) => {
    console.error("Error:", error);
  },
});

// Later: clean up when done
widget.destroy();
```

## 部件模式

### 内置模式

直接将部件嵌入指定的容器元素:

```typescript
const container = document.getElementById("kyi-container");

const widget = kyi("inline", "kyi", accessToken, {
  parentElement: container,
});
```

```html
<div id="kyi-container" style="height: 600px;"></div>
```

### 模式

在居中模式覆盖中显示部件 :

```typescript
const widget = kyi("modal", "kyi", accessToken, {
  onClose: () => console.log("Modal closed"),
});
```

### 绘图模式

在右侧的滑入面板中显示部件 :

```typescript
const widget = kyi("drawer", "kyi", accessToken, {
  onClose: () => console.log("Drawer closed"),
});
```

## 部件范围

这个 `scope` 参数决定要显示的页面 :

| 范围 | 说明 |
| --- | --- |
| `kyi` | 新建 KYI 应用程序流程 |
| `asset-list` | 查看已核实资产清单 |
| `wallet-list` | 查看连接的钱包列表 |

```typescript
// Start a new KYI application
kyi("modal", "kyi", accessToken);

// View assets
kyi("modal", "asset-list", accessToken);

// View wallets
kyi("inline", "wallet-list", accessToken, { parentElement: container });
```

## 检查 KYI 状态( 服务器侧)

从后端查询当前用户的 KYI 状态 :

```typescript
import { checkStatus } from "@bluprynt/kyi-widget-sdk/server";

const status = await checkStatus({
  issuer: "your-partner-id",
  secretKey: process.env.BLUPRYNT_SECRET_KEY!,
  userId: "user-123",
});

console.log(status);
```

## API 参考

### `kyi(mode, scope, accessToken, options?)`

创建 KYI 部件实例 .

**参数:**

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `mode` | `'inline' | 'modal' | 'drawer'` | 部件显示模式 |
| `scope` | `'kyi' | 'asset-list' | 'wallet-list'` | 部件范围 |
| `accessToken` | `string` | JWT 访问符 `generateToken` |
| `options` | `KYIOptions` | 可选配置 |

**选项 :**

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `parentElement` | `HTMLElement` | 集装箱组件(仅内入模式) |
| `onClose` | `() => void` | 部件关闭时调用 |
| `onError` | `(error: Error) => void` | 发生错误时调用 |
| `onReady` | `() => void` | 装入部件并准备就绪时调用 |

**回返情况:** `KYIWidget`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `iframe` | `HTMLIFrameElement` | 提及iframe要素 |
| `destroy` | `() => void` | 删除部件并清理 |

### `generateToken(options)` (服务员侧)

为部件认证创建 JWT 访问令牌 .

**参数:**

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `issuer` | `string` | 您的伴侣识别符 |
| `secretKey` | `string` | 您的 Bluprynt 密钥 |
| `userId` | `string` | 您的内部用户标识符 |
| `expiresIn` | `number` | 已过期秒( 默认 ) : `3600`(中文(简体) ) |

**回返情况:** `Promise<string>` - 签名的JWT标志

### `checkStatus(options)` (服务员侧)

为用户检查 KYI 验证状态 .

**参数:**

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `issuer` | `string` | 您的伴侣识别符 |
| `secretKey` | `string` | 您的 Bluprynt 密钥 |
| `userId` | `string` | 您的内部用户标识符 |

**回返情况:** `Promise<KYIStatus>`

## 框架实例

### 反应

```tsx
import { useEffect, useRef } from "react";
import { kyi, type KYIWidget } from "@bluprynt/kyi-widget-sdk";

function KYIButton({ accessToken }: { accessToken: string }) {
  const widgetRef = useRef<KYIWidget | null>(null);

  const openWidget = () => {
    widgetRef.current = kyi("modal", "kyi", accessToken);
  };

  useEffect(() => {
    return () => widgetRef.current?.destroy();
  }, []);

  return <button onClick={openWidget}>Start KYI</button>;
}
```

## 警卫

-   **永远不要暴露你 `SECRET_KEY` 在客户端.** 托肯一代必须发生在你的后端.
-   访问符是寿命短的JWT. 为每个部件会话创建新令牌 .
-   部件使用 `postMessage` 安全iframe通讯.

## 捐款

欢迎捐款! 请看 [捐款额](https://npmcn.com/package/%40bluprynt/kyi-widget-sdk/CONTRIBUTING.md) 准则.

* * *

建造时小心 [模糊](https://bluprynt.com/)

## 常见问题

### @bluprynt/kyi-widget-sdk 是什么？

Bluprynt KYI 部件 SDK - 在应用程序中嵌入“ 知道你的发行人” 验证

### 如何安装 @bluprynt/kyi-widget-sdk？

在项目目录运行 npm install @bluprynt/kyi-widget-sdk，或使用 pnpm add / yarn add / bun add。

### @bluprynt/kyi-widget-sdk 支持 TypeScript 吗？

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

### @bluprynt/kyi-widget-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bluprynt/kyi-widget-sdk 需要什么版本的 Node\.js？

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

### @bluprynt/kyi-widget-sdk 可以商用吗？

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

### @bluprynt/kyi-widget-sdk 的下载量有多少？

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

### @bluprynt/kyi-widget-sdk 还在维护吗？

最新版本 0\.1\.1 发布于 2026/03/31（7 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。