卡片揭示 - Fluz

本頁假設您已閱讀Secure Elements 概觀——其中涵蓋了建立用戶端權杖、載入 SDK，以及欄位樣式設定，這些同樣適用於此處。

線上預覽

此示範會自動建立權杖並掛載檢視器。若揭示按鈕無回應，請使用重新建立權杖並重新掛載，並使用揭示、僅揭示 CVV或遮罩來試用下方介紹的欄位層級控制。在新分頁開啟 →

建立揭示用權杖

呼叫 POST /v1/client-token，帶入 "purpose": "reveal" 與欲顯示的 virtualCardId：

{
  "purpose": "reveal",
  "virtualCardId": "c107e50b-10f3-449c-92c0-609d9a8cfa2a"
}

將回傳的 clientToken 與 loadToken 直接傳入下方的 createCardViewer。

建立檢視器

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

fields 控制要呈現卡片的哪些部分，以及順序——若省略，預設為 ["pan", "expiry", "cvv"]。每個項目可以是單純的欄位名稱，或 { field, individualReveal } 物件；"pan" 等同於 { field: "pan", individualReveal: true }。僅接受 pan、expiry、cvv 這三個欄位名稱——其它任何值都會在您呼叫 mount() 之前，由 createCardViewer 立即同步擲回 FluzElementsError（error.code === "INVALID_FIELD"）。

欄位	在任何揭示前的遮罩占位符	備註
`pan`	`•••• •••• •••• {last4}`	後四碼來自您用戶端權杖上的卡片中繼資料
`expiry`	真實的 `MM/YYYY`——不遮罩	不視為敏感資料
`cvv`	`•••`	支援 `individualReveal: false`（如下）

individualReveal 在每個欄位上預設為 true。若設為 false，則阻止該欄位被單獨揭示——參見僅揭示單一欄位。它與 reveal() 無關，後者無論設定如何，始終會一次揭示所有欄位。

掛載

await viewer.mount(document.getElementById("card-viewer"));

mount() 會為每個已設定的欄位在您提供的容器元素內附加一個受沙盒保護的 iframe——以預設 fields 而言，是三個獨立的 frame，而非單一整合的 frame——並回傳在每個 frame 完成握手後才會解決的 promise。若發生以下情況，會以 FluzElementsError 拒絕：

您傳給 createCardViewer 的 style 未通過驗證（error.code === "INVALID_STYLE"）——參見欄位樣式設定
某個 frame 未能在 mountTimeoutMs 內完成握手（error.code === "MOUNT_TIMEOUT"；預設 10 秒，可透過 createCardViewer({ ..., mountTimeoutMs }) 設定）
某個 frame 完全載入失敗，或此檢視器已被掛載過（error.code === "MOUNT_FAILED"）——每個 CardViewer 實例只能掛載一次；若需再次掛載，請以 createCardViewer 建立新的實例

揭示與遮罩欄位

await viewer.reveal(); // fetch and show every configured field at once
await viewer.reveal("cvv"); // fetch and show one field, if that field allows it
viewer.setMask("cvv", true); // re-mask a field that's already been revealed
viewer.setMask("cvv", false); // un-mask it again -- see below

reveal(field?)——非同步。從 Fluz 取得真實值並顯示。若不帶參數，會不受 individualReveal 限制，取得並顯示所有設定的欄位。若帶欄位名稱，僅取得並顯示該欄位——除非該欄位設定了 individualReveal: false，此時會以 error.code === "INDIVIDUAL_REVEAL_DISABLED" 拒絕。對未掛載的檢視器，或不在 fields 中的欄位名稱，會以 MOUNT_FAILED 拒絕。
setMask(field, masked, options?)——同步，非非同步。它永不發出任何請求——只切換目前的顯示狀態：
- setMask(field, true) 將欄位重新遮罩回占位符，無論之前是否已被揭示。
- setMask(field, false) 取消遮罩——但僅當該欄位先前已由 reveal() 取得真實值時，才會顯示真實值。若在任何 reveal() 之前呼叫，欄位會維持在占位符，因為尚無可顯示的已取得值。
- setMask(field, true, { hidden: true }) 將欄位完全清空（留白，連占位符也不顯示），而不是顯示圓點/後四碼/到期日。hidden 僅在 masked 為 true 時生效。
- 無整批「全部遮罩」的呼叫——若需重設整個檢視器，請針對 fields 中的每個欄位各呼叫一次 setMask。
destroy()——拆除所有 frame 並解除掛載檢視器。於元件卸載時呼叫，避免在元件消失後仍遺留已掛載的 frame。

僅揭示單一欄位

若要僅揭示單一欄位（例如該欄位旁的「顯示 CVV」按鈕），請呼叫 reveal(field)——每個欄位預設皆允許，常見情境下不需任何設定。若某欄位應「永不」被單獨揭示，只能作為整張卡 reveal() 的一部分顯示，請在 fields 中使用 { field, individualReveal: false } 將其排除：

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

await viewer.reveal("cvv"); // rejects — error.code === "INDIVIDUAL_REVEAL_DISABLED"
await viewer.reveal(); // succeeds — reveals pan, expiry, and cvv together

對已被排除的欄位呼叫 reveal(field)，會在未聯繫 frame-host 的情況下以 FluzElementsError（code: "INDIVIDUAL_REVEAL_DISABLED"）拒絕。無論如何，不帶參數的 reveal() 總會揭示每個已掛載欄位——individualReveal 對其無影響。

這是用戶端整合層級的選擇，而非伺服器強制的能力——它控制您的 UI 可以觸發的行為，而不是授權可返回的資料。請勿將 individualReveal: false 視為安全性邊界。

處理事件

const unsubscribeMount = viewer.onMount(() => {
  // all configured fields have finished rendering
});

const unsubscribeError = viewer.onError((error) => {
  // error.code, error.message
});

onMount 會在每個設定的欄位皆已於 frame 內渲染後觸發一次。onError 會在已掛載的 frame「內部」發生問題時觸發——例如 reveal() 失敗或遭遇速率限制——而非 mount() 或 createCardViewer() 本身的問題；後者會直接拒絕或擲回（見下表）。onMount 與 onError 皆會回傳取消訂閱函式。此功能可能產生的每個 FluzElementsError 以及其出現位置：

代碼	出現位置	意義
`INVALID_FIELD`	由 `createCardViewer` 擲回	某個 `fields` 項目不是 `pan`、`expiry` 或 `cvv`
`INVALID_FRAME_HOST_ORIGIN`	由 `createCardViewer` 擲回	`frameHostOrigin` 不是已辨識的 Fluz frame 主機
`INVALID_STYLE`	由 `mount()` 拒絕	某個 `style` 值未通過驗證
`MOUNT_TIMEOUT`	由 `mount()` 拒絕	某欄位的 frame 未能在 `mountTimeoutMs` 內完成握手
`MOUNT_FAILED`	由 `mount()` 拒絕，或由 `reveal()` / `setMask()` 擲回	某個 frame 載入失敗；檢視器已被掛載；或以未掛載或未知欄位呼叫了 `reveal()` / `setMask()`
`INDIVIDUAL_REVEAL_DISABLED`	由 `reveal(field)` 拒絕	該欄位被設定為 `individualReveal: false`
`FIELD_ERROR`	傳遞給 `onError`	`reveal()` 在掛載後於 frame 內失敗（網路錯誤，或揭示尚不可用）
`RATE_LIMITED`	傳遞給 `onError`	對該授權的揭示嘗試過多——`error.message` 會包含重試等待時間

完整範例

<div id="card-viewer"></div>

<script src="https://secure-cdn-staging.fluz.app/secure-elements/v0.1.0/index.global.js"></script>
<script>
  (async () => {
    const { createCardViewer } = FluzSecureElements;

    const res = await fetch("/mint-reveal-token", { method: "POST" });
    const { clientToken, loadToken } = await res.json();

    const viewer = createCardViewer({
      clientToken,
      loadToken,
      frameHostOrigin: "https://staging.secure.fluz.app",
      fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
      style: {
        fontFamily: "IBM Plex Mono",
        fontSize: "16px",
        color: "#1a1a1a",
      },
    });

    viewer.onError((error) => console.error(error.code, error.message));
    viewer.onMount(() => console.log("card viewer ready"));

    await viewer.mount(document.getElementById("card-viewer"));
  })();
</script>

/mint-reveal-token 是您自己的後端路由——它會使用您的 Fluz OAuth access token 呼叫 POST /v1/client-token，詳見建立用戶端權杖。

下一步

Secure Elements 概觀

權杖建立、SDK 載入、樣式設定與 CSP。

即時示範

揭示、僅揭示 CVV 與遮罩，連線至 staging。

整合範例

可執行的純 HTML 與 React 揭示範例，含權杖建立伺服器。

​線上預覽

​建立揭示用權杖

​建立檢視器

​掛載

​揭示與遮罩欄位

​僅揭示單一欄位

​處理事件

​完整範例

​下一步

Secure Elements 概觀

即時示範

整合範例

線上預覽

建立揭示用權杖

建立檢視器

掛載

揭示與遮罩欄位

僅揭示單一欄位

處理事件

完整範例

下一步