卡片明文显示（Card Reveal）

本页假设你已阅读 Secure Elements 概览 —— 其中涵盖了铸造 client token、加载 SDK 及样式化字段，以上内容同样适用于本功能。

在线预览

该演示会自行铸造令牌并自动挂载查看器。若显示按钮无响应，请使用 Remint token & remount；并通过 Reveal、Reveal CVV only 或 Mask 试用下文介绍的字段级控制。在新标签页打开 →

铸造 reveal 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}`	最后 4 位来自 client token 中的卡片元数据
`expiry`	真实的 `MM/YYYY` —— 不做掩码	不视为敏感信息
`cvv`	`•••`	支持 `individualReveal: false`（见下文）

所有字段的 individualReveal 默认均为 true。将其设为 false 可阻止该字段被单独揭示——见仅揭示单个字段。这与 reveal() 相互独立；后者始终会揭示所有字段，不受此设置影响。

挂载

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

mount() 会按配置的每个字段向你传入的容器元素追加一个沙盒 iframe——对于默认 fields，是 3 个相互独立的 iframe，而非一个合并的 iframe——并在每个 iframe 完成握手后返回已完成的 Promise。若发生以下情况会以 FluzElementsError 拒绝：

传给 createCardViewer 的 style 未通过校验（error.code === "INVALID_STYLE"）——见字段样式化
某个 iframe 未在 mountTimeoutMs 内完成握手（error.code === "MOUNT_TIMEOUT"；默认 10 秒，可通过 createCardViewer({ ..., mountTimeoutMs }) 配置）
某个 iframe 加载失败，或该查看器已被挂载过（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 }) 会将字段完全清空（留空，不显示点、last4 或有效期），而非显示占位符。hidden 仅在 masked 为 true 时生效。
- 不提供批量“全量掩码”方法——如需复位整个查看器，请对 fields 中的每个字段分别调用一次 setMask。
destroy() —— 卸载所有 iframe 并分离查看器。组件卸载时调用它，避免遗留已挂载的 iframe。

仅揭示单个字段

若只想单独揭示某个字段（例如在该字段旁边放一个“显示 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 允许触发的行为，而非 grant 能返回的数据。请不要将 individualReveal: false 视作安全边界。

处理事件

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

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

onMount 在所有配置字段均已在 iframe 内渲染完成后触发一次。onError 用于接收已挂载 iframe 内部发生的问题——例如 reveal() 失败或被限流——而非 mount() 或 createCardViewer() 本身的问题；后者会直接 reject 或抛错（见下文）。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()` 拒绝	某字段的 iframe 未在 `mountTimeoutMs` 内完成握手
`MOUNT_FAILED`	由 `mount()` 拒绝，或被 `reveal()` / `setMask()` 抛出	iframe 加载失败；查看器已被挂载；或在未挂载/未知字段上调用了 `reveal()` / `setMask()`
`INDIVIDUAL_REVEAL_DISABLED`	由 `reveal(field)` 拒绝	该字段被配置为 `individualReveal: false`
`FIELD_ERROR`	发送至 `onError`	挂载后在 iframe 内部发生的 `reveal()` 失败（网络错误，或尚未可揭示）
`RATE_LIMITED`	发送至 `onError`	针对此 grant 的揭示尝试过多——`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。

下一步

Secure Elements 概览

令牌铸造、SDK 加载、样式化与 CSP。

Secure Card Input

另一项 Secure Elements 能力——采集实体卡信息，而非显示已存在的卡片。

在线演示

揭示、仅揭示 CVV 与掩码，运行于 staging。

示例集成

可运行的纯 HTML 与 React 揭示示例，包含令牌铸造服务端。

​在线预览

​铸造 reveal token

​创建查看器

​挂载

​揭示与掩码字段

​仅揭示单个字段

​处理事件

​完整示例

​下一步

Secure Elements 概览

Secure Card Input

在线演示

示例集成

在线预览

铸造 reveal token

创建查看器

挂载

揭示与掩码字段

仅揭示单个字段

处理事件

完整示例

下一步