Web App 集成

本页面介绍 Web & SDK 合约的两种客户端集成方式：将用户重定向至 Unico 托管的流程，以及通过 iFrame SDK 嵌入该流程。

重定向用户

创建流程后，响应中会包含一个指向 Unico 托管流程的 URL。使用该 URL 将用户引导至采集体验。有两种方式可以管理此跳转：

1. 标准重定向

将用户直接重定向至流程 URL。用户完成流程后，Unico 会将其重定向回您在创建流程时指定的 URL。

2. 使用 window.open() 新标签页打开

在新浏览器标签页中打开流程，使用户保持在独立的上下文中。监听您的返回 URL 的 URL 变化，并在流程完成后关闭该标签页。

有关 window.open() API 的详细信息，请参阅 MDN 文档。

iFrame

警告

不符合本文档标准的集成方式可能导致意外中断，且不在 Unico 支持范围内。

不受支持的方式示例：在 WebView 中嵌入 SDK，或直接通过 HTML 标签加载 iFrame。

如何开始

步骤 1 — 安装

by Unico SDK 与 IDPay 使用相同的包：

npm install idpay-b2b-sdk

提示

安装时不要锁定特定版本，这样包管理器会自动拉取最新的次要版本和补丁版本。

在开始之前，请向 Unico 支持团队注册您的域名。所有域名必须使用 HTTPS。

步骤 2 — 调用 init(options)

初始化 SDK 并预加载资源，为终端用户创造更流畅的体验。请尽早在您的流程中调用此方法。

参数	必填	描述
type	是	by Unico 流程请设置为 'IFRAME'
token	是	创建流程 API 返回的流程令牌
env	否	仅测试环境设置为 'uat'

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

步骤 3 — 调用 open(options)

显示预加载的 iFrame 并启动您的页面与 Unico 流程之间的消息通信。

参数	必填	描述
transactionId	是	创建流程 API 返回的流程 ID
token	是	创建流程 API 返回的流程令牌
onFinish	是	流程结束或关闭时执行的回调

onFinish 回调接收一个流程对象，包含交易 ID、重定向 URL 以及完成类型。

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

下方时序图展示了如何使用 SDK 以及 API 结果来配置 iFrame：

安全性

选择使用带身份验证令牌的 iFrame 方案而非 CSP

经过仔细分析，所选方案使用带身份验证令牌的 iframe，而非实施内容安全策略（CSP）。此决策的驱动因素是安全需求以及满足客户需求所需的灵活性。

CSP 的背景与挑战

内容安全策略是保护 Web 应用免受 XSS 和代码注入攻击的强大工具。然而，配置 CSP 策略需要定义一个严格的受信任域名列表。当域名固定且可预测时，这种方式十分有效——但对于使用动态且可变域名的客户而言，这种刚性配置带来了重大挑战。

动态域名的安全风险

使用 CSP 时，动态域名会带来相当大的安全风险。当客户的域名频繁变化或动态创建时，CSP 策略必须不断更新以包含新域名。这不仅增加了维护负担，还会将策略中列出的每个域名暴露为潜在攻击面（如果管理不当）。

使用 iFrame 与身份验证令牌的解决方案

为降低这些风险并满足客户所需的灵活性，所选方案将 iframe 与身份验证令牌相结合，在无需静态域名列表的情况下提供额外的安全层。

工作原理：

• 安全身份验证——每个 iFrame 在加载时携带每笔交易唯一的身份验证令牌，确保只有经授权的用户才能访问内容。令牌会实时验证。
• 内容隔离——iFrame 在独立的浏览上下文中运行，降低了不同来源之间相互干扰的风险，并缓解了潜在攻击。
• 动态域名的灵活性——由于不依赖静态 CSP 策略，该方案可适应客户的动态域名，无需频繁更新策略。