---
title: SDK
description: 如何为 Web 实现 Unico SDK：安装、init/open 方法、全屏指南以及 iFrame + 身份验证令牌安全模型。
canonical: https://developer.unico.io/zh-CN/dual-api/developers/regional-solutions/card-not-present-verification/integration/controlling-the-experience/web/sdk
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- 区域解决方案
- [无卡验证](/zh-CN/dual-api/developers/regional-solutions/card-not-present-verification)
- [集成](/zh-CN/dual-api/developers/regional-solutions/card-not-present-verification/integration/overview)
- [控制体验](/zh-CN/dual-api/developers/regional-solutions/card-not-present-verification/integration/controlling-the-experience/overview)
- Web
- SDK

**本页内容# SDK

对于 Web 使用场景，推荐使用 Unico SDK，原因如下：

更高的安全性；
与您的流程集成的体验；
使用 SDK 时更高的转化率；
更简便的实现方式。

警告使用不符合本文档所规定标准的集成方式，可能会导致系统功能出现意外中断，此类情况不在无卡验证的保障或支持范围内。例如：在 webview 内通过 iFrame 实现 Unico，或通过 HTML 标签实现 iFrame 等。
### 一般准则​

为优化您运营的性能、提升转化率并提供更流畅的用户体验，必须在您的应用程序中以全屏模式实现 Unico SDK。
### 如何开始​

要通过无卡验证 SDK 使用无卡验证，第一步是注册将用作展示用户旅程体验的宿主域名。
危险请通知负责您集成项目的人员或 Unico 支持团队进行此项配置。
要开始使用 SDK，我们应先安装 Unico Web SDK：
```
npm install idpay-b2b-sdk
```

提示安装 Unico SDK 软件包时，部署时不要指定所使用的版本，以便您的依赖管理器始终自动更新到最新的次要版本（minor）和补丁版本（patch）。要查看以往版本，请前往 [npmjs.com/package/idpay-b2b-sdk](https://www.npmjs.com/package/idpay-b2b-sdk?activeTab=versions)。
### 可用方法​

#### `init(options)`​

该方法允许在不依赖交易 ID 的情况下初始化 SDK，从而使最终用户的体验更加流畅。这是因为当交易 ID 和令牌可用时，应用程序已通过该方法完成预加载。如果应用程序未直接调用此方法，最终用户在首次打开 SDK 时将经历较长的加载时间。
参数：

`options` — 接收一个包含配置属性的对象：

`type` — 将被初始化的流程类型。目前，我们提供 `IFRAME` 类型。对于新应用程序，我们建议使用 `IFRAME` 类型，它可以使最终用户体验更加流畅、摩擦更少，因为它无需离开结账页面，且体验可以预加载。

```
import { IDPaySDK } from "idpay-b2b-sdk";IDPaySDK.init({  type: 'IFRAME',  env: 'uat' // 仅在测试环境中需要。});
```

#### `open({ transactionId, token, onFinish? })`​

该方法根据初  始化函数中先前选择的流程类型打开无卡验证体验。对于 REDIRECT 流程，此函数会执行简单的重定向，跳转到无卡验证捕获流程路由。对于 IFRAME 流程，此函数会显示预加载的 iframe，并启动客户页面与无卡验证体验之间的消息传递流程。
参数：

`options` — 接收一个包含配置属性的对象：

`transactionId` — 接收已创建交易的 ID。该 ID 对于获取交易详情并正确完成流程非常重要（可以在通过 API 创建交易时获取）。
`token` — 接收已创建交易的令牌。该令牌对于验证交易并确保只有授权域名可以使用它非常重要（可以在通过 API 创建交易时获取）。
`onFinish(transaction, type)`（可选）— 接收一个回调函数，该函数将在无卡验证捕获流程结束时执行，并传入两个参数：交易对象（`{ captureConcluded, concluded, id }`），以及响应类型——`FINISH` 表示流程成功完成，`ERROR` 表示流程因错误而中断。如果流程中发生错误，交易状态将不会改变，且如果配置了 Webhook 回调，也不会被触发。

```
const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';const transaction = {  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',  concluded: true,  captureConcluded: true};const onFinish = (transaction, type) => {  console.log('response', transaction, type);}IDPaySDK.open({  transactionId,  token,  onFinish});// 您也可以使用以下方法显式关闭 SDKIDPaySDK.close();
```

### 安全性​

在仔细分析了我们所面临的需求和挑战后，我们决定采用基于带身份验证令牌的 iFrame 的解决方案，而非实现内容安全策略（Content Security Policy，CSP）。此决定基于多项与安全性以及满足客户需求所需灵活性相关的考量。
#### CSP 的背景与挑战​

**内容安全策略（Content Security Policy，CSP）** 是一种强大的工具，可保护 Web 应用程序免受各类攻击，例如 **跨站脚本攻击（Cross-Site Scripting，XSS）** 和代码注入。然而，在配置 CSP 策略时，必须定义一份严格的可信域名列表。当域名固定且可预测时，这种方式效果良好。然而，对于经常使用动态和可变域名的客户而言，这  种严格的配置带来了重大挑战。
#### 动态域名带来的漏洞​

在使用 CSP 时，动态域名会带来重大的安全风险。当客户的域名经常变化或是动态创建时，就需要不断更新 CSP 策略以纳入这些新域名。这不仅增加了维护工作量，还暴露了 CSP 策略所适用的域名。如果管理不当，添加到 CSP 策略中的每个域名都可能成为一个潜在的漏洞点。
#### 使用 iFrame 与身份验证令牌的解决方案​

为降低这些风险并满足客户所需的灵活性，我们选择使用结合身份验证令牌的 iFrame。该解决方案提供了额外的安全层，并消除了暴露或管理庞大而动态的域名列表的需求。
#### 工作原理​

**安全身份验证：** 每个 iframe 都会为每笔交易加载一个唯一的身份验证令牌，确保只有获得授权的用户才能访问内容。该令牌会进行实时验证，提供额外的安全性和控制层。
**内容隔离：** 使用 iFrame 可以将内容隔离在独立的上下文中，降低不同来源之间相互干扰的风险，并减轻潜在的攻击。
**动态域名的灵活性：** 由于不依赖静态的 CSP 策略，我们的解决方案可以轻松适应客户的动态域名，而无需持续更新安全策略。
最后更新 于 2026年10月8日**