跳转到主要内容
@clink-ai/agent-elements 把 Clink 的钱包卡片界面嵌进宿主应用。宿主服务端按元素类型签发凭据,前端创建一个元素并挂载到容器里;卡片表单、卡片数据和 3DS 都在 Clink 托管的 iframe 中处理,宿主页面不接触卡数据。
生产环境请锁定 @clink-ai/agent-elements 的版本号。完整参数和方法见 SDK API 参考。

完整链路

Agent Elements 只替换前端卡片界面。凭据仍然必须由宿主服务端签发,因为换取凭据要用 Clink 分配的 client secret。 第 2 步的 client secret 和 portal token 不能下发浏览器。前端能拿到的只有两种东西:paymentMethods 的 card-session token,或 vault 的 vaultId。

四方职责

一、服务端:签发元素凭据

两种元素的凭据来源不同,但都要经过同一套平台鉴权。

1. 换 client token 与 portal token

client token 只用 client_credentials 换取,portal token 再按用户邮箱换取。
  • client_id / client_secret 由 Clink 分配,只放服务端。
  • portal token 只支持 email,不支持传 customer_id。
  • 邮箱必须已经授权给该 client;未授权会返回 71211003 The redirect URI is not registered for this client。
  • client token 与 portal token 有效期都是 3600s。

2. paymentMethods:创建 card-session

响应里的 access_token(scope card:manage)就是 paymentMethods 元素的凭据,有效期 1799s。它只能访问当前用户的卡片接口,可以下发给浏览器。

3. vault:创建 vault session

  • vault_id 下发给 vault 元素,有效期约 30 分钟。
  • url 是免登录绑卡页,供用户直接在浏览器打开;SDK 接入不使用它。
  • vault token 由 iframe 用 vaultId 兑换,有效期约 899s,宿主不接触。
client secret、client token、portal token 都只能留在服务端。包装接口向前端只返回 { token } 或 { vaultId }。

二、前端:初始化并挂载

环境

environment 决定 iframe 加载哪个 Clink 应用地址,也决定服务端该请求哪套 API。 environment 必传:接入联调用 sandbox(UAT),上线用 production。跨环境不要混用凭据,否则会 401。应用地址只由 environment 决定,SDK 不接受运行时覆盖。

安装

包同时提供 ESM 与 IIFE 产物,见 构建产物。

创建实例

一个 AgentElements 实例只能创建一个元素。同时使用两个元素时创建两个实例。

创建元素

元素类型决定凭据和可用的挂载选项。凭据在 createElement 时传入,必填且不能为空。

挂载

容器可以是 CSS 选择器或 HTMLElement,需要有稳定宽度;高度由 SDK 设置,加载后随内容增长,宿主不要固定高度。宿主运行在支持 iframe 与 postMessage 的现代浏览器中。 挂载选项只在下一次挂载时生效;需要调整时先 unmount 再 mount。 挂载选项只是展示配置,会被编码进 iframe 地址。不要放 token 等敏感值。

三、事件与状态同步

事件按元素划分,通过 element.on / element.off 订阅。在 mount() 之前注册,避免漏掉事件。
error.source 取值:

token 过期

paymentMethods 收到 token-expired 后,从宿主后端换新的 card-session token,再调用 setToken:
新 token 到达后 iframe 会重新加载卡片数据,并重置「每周期只上报一次」的计数。mount 之前调用 setToken 只更新内存值,等下一次 init 才下发。 vault 没有可刷新的 token:session 失效后重新申请 vaultId 并重建元素。

清理

destroy() 会移除 iframe、关闭已打开的 3DS 浮层并清理元素上的监听。实例不可复用。unmount() 只移除 iframe 和 wrapper,订阅会保留,可以再次挂载。

四、外观

外观只在创建实例时设置:
这些选项在 SDK 发送 init 时应用。运行期只能用 setLocale 切换语言;主色和圆角创建后不可更改。

五、限制

  • 一个 AgentElements 实例只能创建一个元素;需要同时使用 paymentMethods 与 vault 时创建两个实例。
  • 卡片界面只能通过预设项调整,不提供自定义 CSS。
  • 3DS 只通过 iframe 浮层承载,不支持弹窗或整页跳转方式。
  • token / vaultId 的获取与刷新由宿主服务端负责。