將 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. 初始化小工具

腳本載入後，呼叫 init()，傳入你的 API 金鑰、交易細節，以及來自伺服器的 patToken。

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() 接受蛇形命名的 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`	是	已簽章的預先核准交易 token。請在你的伺服器上產生，切勿在瀏覽器 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。其他都會針對你已簽章的 token 進行驗證，因此錯誤的 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 觸發或使用者關閉小工具時，才將工作階段視為結束。

回呼會收到什麼

當可得時，兩個回呼都會包含將工作階段與你的紀錄關聯的識別碼，以及執行該流程之 Fluz 帳戶的聯絡資料。這些由 Fluz 在伺服器端依據你已簽章的 token 與使用者的工作階段填入，因此是 Fluz 所紀錄的值，而非頁面自行組裝的內容。

欄位	來源
`userId`	Fluz 使用者 id（UUID）。與Webhook 事件搭載的相同 id，因此結果與後續 Webhook 可對應。
`accountId`	執行流程的 Fluz 帳戶 id（UUID）：使用者的個人帳戶，或商務流程中的商務帳戶。
`externalReferenceId`	你簽入 `patToken` 的 `externalId`，原樣回傳給你。
`email`	執行該流程的 Fluz 帳戶電子郵件。
`phoneNumber`	該帳戶的電話號碼（若有紀錄）。

請獨立讀取每個欄位；不要假設欄位集合是完整的。

externalReferenceId 來自你的 token，因此可在使用者登入前發生的失敗中依然存在。
其餘四個來自 Fluz 帳戶，僅在工作階段進行到該步驟後才會出現。
在你的 token 驗證前即發生的失敗（例如 token 過期、缺少應用程式權限）不會攜帶任何欄位。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`	工作階段 token 已過期。	產生新的 `patToken` 並重新開啟小工具。
`WIDGET-005`	工作階段在完成前被終止。	開始新的工作階段。
`AUTH-0033`	該帳戶已連結至你應用程式的另一位使用者。	導引用戶前往他們已連結的帳戶。
`US-0005`	使用者未完成身分驗證：檢查直接失敗或帳戶待審。	使用者會留在小工具中且可重試。不要授予仰賴已驗證使用者的存取權。
`G-0004`	無法完成交易。	使用者停留在確認畫面且可重試。不要結算或釋出資金。
`G-0001`	我們端發生問題。	重試一次，之後發出警示。

將任何未知代碼視同 G-0001。新代碼會在不破壞相容性的前提下陸續推出。

以行內方式渲染小工具（僅限 staging）

container 選項僅在 staging 可用。正式環境整合必須使用預設的全螢幕模態視窗，直到該功能上線。

預設情況下，小工具會在你的頁面上掛載固定、覆蓋整個視窗的 overlay。傳入 container 後，它會在你自行定位與調整大小的元素內渲染，不會有 overlay、滾動鎖定或頁面接管。

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 px。 每個畫面（包含文件擷取、2FA 與 PIN 輸入）在此尺寸皆受支援。更小的版面不受支援。
沒有最大值限制。 寬容器會呈現桌面版版面（包含交易摘要側欄），窄容器則呈現行動版版面。

與模態視窗的差異

行為	模態	行內
疊加在你的頁面上	是	否
Escape 鍵可關閉小工具	是	否，你的頁面保留該按鍵
瀏覽器返回鍵會被攔截	是	否，你的頁面保留其歷史紀錄
小工具自身的關閉控制	關閉模態視窗	移除小工具並清空你的容器

請規劃最後一列：當使用者關閉行內小工具時，onClose 會觸發且你的容器會被清空，因此請在 onClose 中渲染應該替換小工具的內容。

容器錯誤

若容器無法使用，將不會有任何渲染，onOpen 也不會觸發，且腳本會記錄錯誤：

在 init()： container 既不是元素也不是非空字串。小工具將維持未設定狀態，之後的 open() 會被拒絕。
在 open()： 選擇器沒有匹配任何元素、不是有效的 CSS，或元素未附加至文件。

無法解析的容器永遠不會退回使用全螢幕模態視窗。

container 選擇器會在呼叫 open() 時才解析，而非於 init()，因此可在元素尚未存在時先呼叫 init()。

​1. 載入小工具腳本

​2. 初始化小工具

​3. 開啟小工具

​初始化選項

​方法

​處理結果

​回呼的行為方式

​回呼會收到什麼

​錯誤代碼

​以行內方式渲染小工具（僅限 staging）

​尺寸

​與模態視窗的差異

​容器錯誤

1. 載入小工具腳本

2. 初始化小工具

3. 開啟小工具

初始化選項

方法

處理結果

回呼的行為方式

回呼會收到什麼

錯誤代碼

以行內方式渲染小工具（僅限 staging）

尺寸

與模態視窗的差異

容器錯誤