跳转到主要内容

SDK

Markdown

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

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

使用不符合本文档所规定标准的集成方式，可能会导致系统功能出现意外中断，此类情况不在无卡验证的保障或支持范围内。

例如：在 webview 内通过 iFrame 实现 Unico，或通过 HTML 标签实现 iFrame 等。

一般准则​

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

如何开始​

要通过无卡验证 SDK 使用无卡验证，第一步是注册将用作展示用户旅程体验的宿主域名。

危险

请通知负责您集成项目的人员或 Unico 支持团队进行此项配置。

要开始使用 SDK，我们应先安装 Unico Web SDK：

npm install unico-journey-sdk
原名 idpay-b2b-sdk

该软件包此前以 idpay-b2b-sdk 名称发布。它是同一个 SDK，只是更换了名称，并遵循相同的版本线。只有 2.3.0 及更高版本 以 unico-journey-sdk 名称发布；更早的版本仍以原来的 idpay-b2b-sdk 名称提供。

提示

安装 Unico SDK 软件包时，部署时不要指定所使用的版本，以便您的依赖管理器始终自动更新到最新的次要版本（minor）和补丁版本（patch）。

要查看以往版本，请前往 npmjs.com/package/idpay-b2b-sdk。

可用方法​

init(options)​

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

参数：

  • options — 接收一个包含配置属性的对象：
    • type — 将被初始化的流程类型。目前，我们提供 IFRAME 类型。对于新应用程序，我们建议使用 IFRAME 类型，它可以使最终用户体验更加流畅、摩擦更少，因为它无需离开结账页面，且体验可以预加载。
import { IDPaySDK } from "unico-journey-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
});

// 您也可以使用以下方法显式关闭 SDK
IDPaySDK.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 策略，我们的解决方案可以轻松适应客户的动态域名，而无需持续更新安全策略。
最后更新 于