> ## 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.

# 透過 Widget 進行驗證

> 讓 Fluz widget 內建處理身分驗證，無需讓任何身分資料經過你的系統。

如果你嵌入 Fluz widget，就會一併包含驗證功能。你不需要自行建立驗證流程、蒐集身分欄位或處理文件——widget 會將驗證呈現為一道關卡，通過後才會讓顧客繼續。

這是唯一一種顧客身分資訊完全不會觸及你基礎設施的路徑，通常也是選擇它的決定性因素。

<Info>
  **先決條件**

  * 已在 Developer Portal 設定的 widget 應用程式，並完成 OAuth 設定。請參閱 [設定 App Widget](/developers/configure-app-widget)。
  * 你的應用程式已由 Fluz 啟用 `VERIFY_KYC` scope。請參閱 [必要的 scope](/user-kyc-verification#required-scope)。
  * 已註冊的 webhook 端點。請參閱 [驗證顧客](/user-kyc-verification#set-up-a-webhook)。
</Info>

## 驗證在流程中的位置

驗證是 widget 正常序列中的一步，而非獨立整合：

<Steps>
  <Step title="你的頁面呼叫 FluzEmbedded.init()">
    widget 會在 iframe 中開啟。
  </Step>

  <Step title="顧客登入或註冊">
    如果他們尚未擁有 Fluz 帳戶，widget 會建立一個。
  </Step>

  <Step title="widget 檢查驗證狀態">
    若顧客已通過驗證，便直接繼續；若尚未，會在此進行驗證。
  </Step>

  <Step title="顧客完成其餘步驟">
    設定 PIN 與授權 OAuth scopes。
  </Step>

  <Step title="顧客完成交易">
    完成確認，接著結束。
  </Step>
</Steps>

由於驗證位於交易之前，無法通過驗證的顧客將完全不會進入交易步驟。

## 顧客的實際體驗

當未驗證的顧客到達關卡時，widget 會先嘗試在背景中靜默驗證。許多顧客在此階段就可通過，無需提供任何資料。

若未能解決，widget 會在 iframe 內呈現驗證表單，並預先填入 Fluz 既有資料。顧客檢視、補齊缺漏並送出。其後 widget 會顯示等待狀態，處理完成後自動往下。

若驗證仍未成功，widget 會升級為文件驗證——在同一個 iframe 內擷取政府核發的身分證件與自拍照。

<Note>
  以上全在 widget 內發生。你不需要偵測顧客所處階段，也不需自行觸發升級。
</Note>

## Scopes

Widget 應用程式會在 OAuth 授權步驟自動請求所需的 scopes，包括 `VERIFY_KYC`。你不需要將它手動加到 widget 的 scope 清單。

不過，你仍需讓 Fluz 在應用程式層級啟用 `VERIFY_KYC`。若未啟用，widget 將因權限不足而載入失敗，而不是略過驗證。

<Warning>
  產生你要以 `patToken` 傳給 widget 的短效期權杖時，請在 `Authorization: Basic` 標頭使用你的 **API Key**——不要使用 OAuth client ID，也不要使用 `app_id`。使用錯誤的值是 widget 載入失敗最常見的原因。請參閱 [取得你的 API 憑證](/get-started/api-credentials)。
</Warning>

## 知道驗證結果

widget 會直接告知顧客結果，但你的應用程式不應從 widget 關閉來推測驗證狀態。請改用 webhooks。

當顧客在 widget 中**開始**驗證時，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>

## 將 widget 與 API 結合

widget 與 API 在每位顧客之間共用同一個驗證狀態，因此兩種方式能無縫組合：

* 透過 API 完成驗證的顧客，會直接通過 widget 的關卡。
* 在 widget 中完成驗證的顧客，對你的 API 呼叫同樣已驗證。
* 在任一管道用盡嘗試次數的顧客，在兩邊都視為用盡。

若你在導入流程中透過 API 驗證顧客，之後再將他們交給 widget，請檢查顧客目前的驗證狀態，而不是假設 widget 會再提供他們一次嘗試。

## 測試

在測試環境中以發佈的測試身分完整跑一次 widget 流程，包括刻意的拒絕案例，以查看升級到文件驗證的情況。測試環境的 widgets 會連到測試而非正式機器——請確認你載入的是測試環境的 widget script 與 base URL。請參閱 [測試 KYC 流程](/test-kyc-flows) 與 [測試與正式環境](/concepts/environments)。