> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过小部件完成验证

> 让 Fluz 小部件将身份验证作为内置步骤处理，身份数据不经过你的系统。

如果你嵌入了 Fluz 小部件，验证功能会随之提供。你无需构建验证流程、收集身份字段或处理证件——小部件会将验证作为一道闸门呈现，并在放行客户继续之前完成验证。

这是唯一一条客户身份信息完全不接触你基础设施的路径，这通常是选择它的决定性因素。

<Info>
  **先决条件**

  * 已在 Developer Portal 配置的小部件应用，并设置好 OAuth。参见 [配置应用小部件](/developers/configure-app-widget)。
  * 由 Fluz 在你的应用上启用 `VERIFY_KYC` scope。参见 [所需 scope](/user-kyc-verification#required-scope)。
  * 已注册的 webhook 端点。参见 [验证客户](/user-kyc-verification#set-up-a-webhook)。
</Info>

## 验证在何处介入

验证是小部件正常序列中的一步，而不是单独的集成：

<Steps>
  <Step title="你的页面调用 FluzEmbedded.init()">
    小部件在 iframe 中打开。
  </Step>

  <Step title="客户登录或注册">
    如果他们还没有 Fluz 账户，小部件会创建一个。
  </Step>

  <Step title="小部件检查验证状态">
    如果客户已完成验证，则直接继续。否则，此处执行验证。
  </Step>

  <Step title="客户完成其余步骤">
    设置 PIN 和授权 OAuth scope。
  </Step>

  <Step title="客户完成其交易">
    确认，然后完成。
  </Step>
</Steps>

由于验证位于交易之前，无法通过验证的客户将根本无法到达交易步骤。

## 客户会经历什么

当未验证客户到达闸门时，小部件首先会在后台静默尝试验证。许多客户在此时无需提供任何信息就能通过。

如果仍未解决，小部件会在 iframe 内呈现一份验证表单，并自动填写 Fluz 已掌握的信息。客户进行审核，补充缺失项并提交。随后小部件会显示等待状态，处理完成后会自动继续。

如果验证仍未成功，小部件会在同一 iframe 内将客户升级到证件验证——拍摄他们的政府颁发身份证件和自拍照。

<Note>
  以上全部在小部件内完成。你无需检测客户所处阶段，也无需手动触发升级。
</Note>

## Scopes

小部件应用会在 OAuth 授权步骤中自动请求所需的 scopes，包括 `VERIFY_KYC`。你不必将其手动加入小部件的 scope 列表。

你仍需由 Fluz 在应用本身启用 `VERIFY_KYC`。若未启用，小部件将因缺少权限错误而无法加载，而不是跳过验证。

<Warning>
  生成传给小部件作为 `patToken` 的短期令牌时，在 `Authorization: Basic` 头中使用你的 **API Key**——不是你的 OAuth client ID，也不是你的 `app_id`。使用错误的值是小部件无法加载的最常见原因。参见 [获取 API 凭证](/get-started/api-credentials)。
</Warning>

## 如何获知结果

小部件会直接告知客户其结果，但你的应用不应根据小部件关闭来推断验证状态。请改为依赖 webhooks。

当客户在小部件中**开始**验证时，Fluz 会发出 `WIDGET_KYC_INITIATION`。这需要 `VERIFY_KYC` scope。

```json theme={null}
{
  "eventType": "WIDGET_KYC_INITIATION",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123"
}
```

<Note>
  该事件标记验证的**开始**，而非结果。使用 `externalReferenceId` 将事件映射到你自己的客户记录，并同时订阅验证结果事件，以便了解最终结果。参见 [Webhooks](/fluz-dashboard/webhooks)。
</Note>

## 将小部件与 API 结合

小部件与 API 在每位客户层面共享同一个验证状态，因此两种方式可以自然组合：

* 通过 API 验证过的客户会直接通过小部件的闸门。
* 在小部件中通过验证的客户对你的 API 调用同样被视为已验证。
* 在一个渠道用尽尝试次数的客户，在两个渠道中都已用尽。

如果你在注册期间通过 API 验证客户，随后再将他们交给小部件，请检查客户当前的验证状态，而不是假设小部件会再给他们一次尝试。

## 测试

在 staging 中运行完整的小部件流程，使用公布的测试身份，包括故意的拒绝情形，以便查看升级到证件验证的流程。Staging 小部件指向的是 staging 环境而非生产环境——请确认你加载的是 staging 的小部件脚本和基础 URL。参见 [测试 KYC 流程](/test-kyc-flows) 和 [Staging 与正式环境](/concepts/environments)。