卡片揭示 - Fluz

本頁假設你已閱讀過安全元件概覽——其中涵蓋了鑄造 client token、載入 SDK 與欄位樣式設計，這些都同樣適用於此。

線上示範

此示範會自行鑄造 token 並自動掛載檢視器。若揭示按鈕停止回應，請使用Remint token & remount，並可透過 Reveal、Reveal CVV only 或 Mask 試用下文介紹的欄位層級控制。在新分頁開啟 →

鑄造揭示用的 token

呼叫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 這三個欄位名稱——其他任何值都會在 createCardViewer 呼叫時同步擲出 FluzElementsError（error.code === "INVALID_FIELD"），在你呼叫 mount() 前就會發生。

Field	揭示前的遮罩佔位符	備註
`pan`	`•••• •••• •••• {last4}`	後四碼來自你的 client token 內的卡片中繼資料
`expiry`	真實的 `MM/YYYY`——不會遮罩	不視為敏感資訊
`cvv`	`•••`	支援 `individualReveal: false`（如下）

individualReveal 在每個欄位預設為 true。若將其設為 false，會阻止該欄位被單獨揭示——請見僅揭示單一欄位。它與 reveal() 無關，後者無論此設定為何都會一次揭示所有欄位。

掛載

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

mount() 會針對你設定的每個欄位，在你傳入的容器元素中新增一個受沙盒保護的 iframe——以預設的 fields 而言，會是三個獨立的 frame，而非一個合併的 frame——並在每個 frame 完成握手後才回傳 fulfilled 的 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 以及其出現位置：

Code	出現位置	意義
`INVALID_FIELD`	由 `createCardViewer` 擲出	某個 `fields` 項目不是 `pan`、`expiry` 或 `cvv`
`INVALID_FRAME_HOST_ORIGIN`	由 `createCardViewer` 擲出	`frameHostOrigin` 不是已被 Fluz 認可的 frame host
`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.fluz.app/secure-elements/v0.3.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，如鑄造 client token所述。

後續步驟

安全元件概覽

Token 鑄造、SDK 載入、樣式設計與 CSP。

安全卡片輸入

另一個安全元件能力——用於收集實體卡，而非揭示現有卡片。

即時示範

揭示、僅揭示 CVV 與遮罩，連線至預備環境。

範例整合

可執行的純 HTML 與 React 揭示範例，附帶 token 鑄造伺服器。

​線上示範

​鑄造揭示用的 token

​建立檢視器

​掛載

​揭示與遮罩欄位

​僅揭示單一欄位

​處理事件

​完整範例

​後續步驟

安全元件概覽

安全卡片輸入

即時示範

範例整合

線上示範

鑄造揭示用的 token

建立檢視器

掛載

揭示與遮罩欄位

僅揭示單一欄位

處理事件

完整範例

後續步驟