将 JS 小部件添加到你的页面

开始之前： 你的服务器必须为每个会话生成一个 patToken 并将其提供给你的页面。参见设置你的服务器。

1. 加载小部件脚本

将此加载器添加到你的页面。它会注入小部件脚本，并在 FluzEmbedded 就绪时才解析，这样其余代码不会在小部件存在之前运行。

<script>
  function loadFluzWidget() {
    return new Promise((resolve, reject) => {
      const get = () => (typeof FluzEmbedded !== "undefined" ? FluzEmbedded : null);
      if (get()) return resolve(get());

      const script = document.createElement("script");
      script.src =
        "https://storage.googleapis.com/fluz-fluz-file-uploads-prod-ricuyxowbwlfprel/widgets/fluz-embedded-payment-widget.js?v1.1.1";
      script.async = true;
      script.onload = () =>
        get() ? resolve(get()) : reject(new Error("FluzEmbedded is not available"));
      script.onerror = () => reject(new Error("Failed to load the Fluz widget script"));
      document.head.appendChild(script);
    });
  }
</script>

2. 初始化小部件

脚本加载完成后，使用你的 API key、交易详情以及来自服务器的 patToken 调用 init()。

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    apiKey: "",           // Your api_key
    patToken: "",         // The patToken generated on your server
    transaction_type: "", // e.g. DEPOSIT or WITHDRAW (see Init options)
    amount: 0.0,          // Amount in dollars and cents
    onOpen: () => console.log("Widget opened"),
    onClose: () => console.log("Widget closed"),
    onSuccess: (result) => console.log("Flow completed", result.externalReferenceId),
    onError: (error) => console.error(error.code, error.message),
  });
});

init() 接受蛇形命名（snake case）的 transaction_type。签名的 patToken 内部声明为 transactionType。二者必须描述同一笔交易。

3. 打开小部件

选择用户如何启动小部件。两种方式都在 init() 之后运行。

使用你自己的按钮
使用 Fluz 按钮

将 open() 绑定到页面上已存在的按钮。

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({ /* options from step 2 */ });

  document
    .getElementById("existing-button") // replace with your selector
    ?.addEventListener("click", () => FluzEmbedded.open());
});

向页面上的某个元素追加一个已标注的 Fluz 按钮。点击该按钮会调用 open()。

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({ /* options from step 2 */ });

  const el = document.getElementById("btn-container"); // replace with your selector
  if (el) FluzEmbedded.renderButton(el);
});

初始化选项

选项	是否必填	作用
`apiKey`	是	你的应用 `api_key`，来自 Installation 选项卡。
`patToken`	是	已签名的预批准交易令牌。在你的服务器生成，切勿在浏览器 JavaScript 中生成。
`transaction_type`	是	`DEPOSIT`、`WITHDRAW`、`CASH_DEPOSIT`、`PAY_IN`、`PAYOUT`、`KYB` 或 `ENROLLMENT`。
`amount`	大多数类型	数字。对于不包含金额的类型（如 `KYB` 和 `ENROLLMENT`）省略。
`container`	否	仅限 Staging。一个元素或 CSS 选择器。设置后，小部件会内联渲染在该元素内，而不是以全屏模态打开。参见内联渲染。
`onOpen`	否	当小部件被添加到页面时调用。
`onClose`	否	当小部件被移除时调用，无论是用户操作还是你调用 `close()`。
`onSuccess`	否	流程完成后调用一次，不会再次调用。接收会话详情。
`onError`	否	每次尝试失败时调用：身份验证、交易或小部件本身。接收 `{ code, message }` 以及任何已知的会话详情。

init() 只检查脚本自身所需内容：apiKey、patToken、transaction_type，以及可解析的 container。其他内容会根据你签名的令牌进行校验，因此错误的 transaction_type 或缺失的 amount 会通过 onError 反馈给你，而不会以你的代码看不到的控制台消息出现。

方法

方法	作用
`FluzEmbedded.init(options)`	配置小部件。拒绝无效选项并记录原因。
`FluzEmbedded.open()`	渲染小部件。`openModal()` 是为旧版集成保留的别名。
`FluzEmbedded.close()`	移除小部件并触发 `onClose`。
`FluzEmbedded.renderButton(element)`	追加一个已标注的按钮，点击后调用 `open()`。
`FluzEmbedded.isOpen()`	返回小部件当前是否已渲染。

处理结果

onOpen 和 onClose 只表明小部件出现和消失，并不表示用户是否完成。要了解流程如何结束，传入 onSuccess 和 onError。两者均为可选；即使都不传，小部件仍然可用，只是你收不到结果。

FluzEmbedded.init({
  apiKey: "your-api-key",
  transaction_type: "PAY_IN",
  amount: 50.0,
  patToken: "your-token",
  onSuccess: ({ userId, accountId, externalReferenceId, email }) => {
    // UI only: show the user they're done and move them along.
    showConfirmation(externalReferenceId);
  },
  onError: ({ code, message, externalReferenceId }) => {
    if (code === "WIDGET-004") {
      // The token expired. Mint a fresh one and reopen.
      return refreshTokenAndReopen();
    }
    if (code === "US-0005" || code === "G-0004") {
      // The user is still in the widget and may retry.
      // Record the attempt; don't tear down your own flow.
      return recordFailedAttempt(code, externalReferenceId);
    }
    reportToSupport(code, message, externalReferenceId);
  },
});

不要在 onSuccess 中结算。 它在访客的浏览器中运行，不携带可验证的交易记录，且任何人都可以从控制台调用。仅将其用于用户可见的内容：确认、重定向、清除加载动画。仅从你的服务器执行记账入账、发货释放或记入账本，并由Webhook或你自行获取并验证的交易驱动。

回调的行为方式

onSuccess 是最终态。 它最多触发一次，之后不会再有结果回调，因此已完成的流程不会再报告错误。
onError 报告的是一次尝试，而非最终裁定。 身份验证失败或付款被拒的用户仍在小部件内且可以重试。onError 在一个会话中可能触发多次，之后仍可能出现一次 onSuccess。
两个回调都不会关闭小部件。 用户会停留在界面，直至其自行关闭，此时触发 onClose。

只在 onSuccess 触发或用户关闭小部件时，将会话视为结束。

回调接收的内容

在可用时，两个回调都会包含将会话与你的记录关联的 id，以及运行该会话的 Fluz 账户的联系方式。Fluz 在服务器端根据你签名的令牌和用户会话填充这些值，因此这些是 Fluz 记录下的值，而非页面组装的内容。

字段	来源
`userId`	Fluz 用户 id（UUID）。与Webhook 事件携带的 id 相同，因此结果与后续 Webhook 可对齐。
`accountId`	本次流程对应的 Fluz 账户 id（UUID）：用户的个人账户，或企业流程中的企业账户。
`externalReferenceId`	你在 `patToken` 中签入的 `externalId`，原样返还给你。
`email`	运行该流程的 Fluz 账户的电子邮箱。
`phoneNumber`	该账户的电话号码（如已记录）。

分别读取每个字段；不要假设集合是完整的。

externalReferenceId 来自你的令牌，因此它能在用户登录前发生的失败中幸存。
其余四个来自 Fluz 账户，只有当会话进展到那一步时才会出现。
在你的令牌验证之前发生的失败（令牌过期、应用权限缺失）不携带任何内容。onError 仅接收 code 和 message。

email 和 phoneNumber 描述的是用户登录的 Fluz 账户，可能与您在 patToken 中传入的值不同。这些字段用于标识会话；它们不是发生事件的记录。使用 externalReferenceId 在你的系统中定位正确的行，然后在采取行动前通过 Webhook 或 API 调用确认结果。

email 和 phoneNumber 需要已注册的 Origin。 Fluz 会将结果消息发送到你应用 OAuth 选项卡中的 Origin，并且只有当该 Origin 已设置且可用时才会包含联系方式。若无已备案的 Origin，你仍会收到三个 id。请将 Origin 指向嵌入小部件的页面。如果它指向一个你不再嵌入的主机，浏览器将拒绝投递消息，于是 onSuccess 和 onError 将不再触发。onOpen、onClose 以及关闭控件不受影响。唯一迹象是在浏览器控制台中的 postMessage 目标源不匹配。参见配置 App Widget。

错误代码

onError 会接收用于分支的稳定 code，以及用于记录的人类可读 message。US-0005 和 G-0004 表示用户可以重试的失败；其他任何代码都表示会话无法继续。

代码	发生了什么	如何处理
`WIDGET-001`	小部件链接缺少必需参数。	检查传给 `init()` 的值。不要重试。
`WIDGET-002`	小部件链接包含无效参数。	检查 `transaction_type` 和 `amount`。不要重试。
`WIDGET-003`	你的应用缺少小部件需要的权限。	联系你的客户经理。不要重试。
`WIDGET-004`	会话令牌已过期。	生成新的 `patToken` 并重新打开小部件。
`WIDGET-005`	会话在完成前被终止。	开始一个新会话。
`AUTH-0033`	该账户已链接到你应用的另一位用户。	将用户引导至他们已连接的账户。
`US-0005`	用户未完成身份验证：检查失败且无后续步骤，或账户处于审核中。	用户仍在小部件内且可以重试。不要授予依赖已验证用户的访问权限。
`G-0004`	交易无法完成。	用户停留在确认界面且可以重试。不要结算或释放资金。
`G-0001`	我们这边发生了问题。	重试一次，然后告警。

将任何未识别的代码视为 G-0001。新代码会随时间推出而不构成破坏性变更。

内联渲染小部件（仅限 staging）

container 选项仅在 staging 可用。生产环境集成必须使用默认的全屏模态，直至该功能在生产环境中发布。

默认情况下，小部件会在你的页面上挂载一个固定的、覆盖整个视口的遮罩层。传入 container 后，它会在你自行定位和设定尺寸的元素内渲染，不包含遮罩、滚动锁定或页面接管。

loadFluzWidget().then((FluzEmbedded) => {
  FluzEmbedded.init({
    apiKey: "",           // Your api_key
    patToken: "",         // The patToken generated on your server
    transaction_type: "WITHDRAW",
    amount: 50.0,
    container: "#fluz-widget", // a CSS selector or the element itself
    onClose: () => {
      // The container is now empty. Render what should replace the widget.
    },
  });

  FluzEmbedded.open();
});

尺寸

小部件会以 100% 宽高填充你的容器，并且从不改变容器大小。超出容器高度的内容会在小部件内滚动，而不是你的页面滚动。

在 CSS 中为容器设置显式宽高。 没有高度时，小部件会回退到浏览器的默认 iframe 高度 150px，这是此类集成中最常见的错误。若打开时容器过小，脚本会在控制台记录警告。
最小支持尺寸为 320 × 480 像素。 包括文档采集、双重验证（2FA）和 PIN 输入在内的每个界面都支持该尺寸。更小的布局不受支持。
无上限。 宽容器会获得桌面布局（含交易摘要面板）；窄容器会获得移动端布局。

与模态的差异

行为	模态	内联
页面顶部覆盖层	是	否
Esc 可关闭小部件	是	否，按键仍归你的页面
拦截浏览器后退按钮	是	否，历史记录仍归你的页面
小部件自带关闭控件	关闭模态	移除小部件并清空你的容器

注意最后一行：当用户关闭内联小部件时，会触发 onClose 且你的容器被清空，因此请在 onClose 中渲染其替代内容。

容器错误

如果容器无法使用，将不会渲染，onOpen 不会触发，脚本会记录错误：

在 init() 时： container 既不是元素也不是非空字符串。小部件保持未配置状态，随后调用 open() 将被拒绝。
在 open() 时： 选择器未匹配任何元素、不是有效 CSS，或元素未附加到文档。

无法解析的容器绝不会回退到全屏模态。

container 选择器会在调用 open() 时解析，而不是在 init() 时解析，因此在元素尚不存在前调用 init() 是可以的。

​1. 加载小部件脚本

​2. 初始化小部件

​3. 打开小部件

​初始化选项

​方法

​处理结果

​回调的行为方式

​回调接收的内容

​错误代码

​内联渲染小部件（仅限 staging）

​尺寸

​与模态的差异

​容器错误

1. 加载小部件脚本

2. 初始化小部件

3. 打开小部件

初始化选项

方法

处理结果

回调的行为方式

回调接收的内容

错误代码

内联渲染小部件（仅限 staging）

尺寸

与模态的差异

容器错误