@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,宿主不接触。
二、前端:初始化并挂载
环境
environment 决定 iframe 加载哪个 Clink 应用地址,也决定服务端该请求哪套 API。
environment 必传:接入联调用 sandbox(UAT),上线用 production。跨环境不要混用凭据,否则会 401。应用地址只由 environment 决定,SDK 不接受运行时覆盖。
安装
创建实例
AgentElements 实例只能创建一个元素。同时使用两个元素时创建两个实例。
创建元素
元素类型决定凭据和可用的挂载选项。凭据在createElement 时传入,必填且不能为空。
挂载
HTMLElement,需要有稳定宽度;高度由 SDK 设置,加载后随内容增长,宿主不要固定高度。宿主运行在支持 iframe 与 postMessage 的现代浏览器中。
挂载选项只在下一次挂载时生效;需要调整时先 unmount 再 mount。
挂载选项只是展示配置,会被编码进 iframe 地址。不要放 token 等敏感值。
三、事件与状态同步
事件按元素划分,通过element.on / element.off 订阅。在 mount() 之前注册,避免漏掉事件。
error.source 取值:
token 过期
paymentMethods 收到 token-expired 后,从宿主后端换新的 card-session token,再调用 setToken:
mount 之前调用 setToken 只更新内存值,等下一次 init 才下发。
vault 没有可刷新的 token:session 失效后重新申请 vaultId 并重建元素。
清理
destroy() 会移除 iframe、关闭已打开的 3DS 浮层并清理元素上的监听。实例不可复用。unmount() 只移除 iframe 和 wrapper,订阅会保留,可以再次挂载。
四、外观
外观只在创建实例时设置:
这些选项在 SDK 发送
init 时应用。运行期只能用 setLocale 切换语言;主色和圆角创建后不可更改。
五、限制
- 一个
AgentElements实例只能创建一个元素;需要同时使用paymentMethods与vault时创建两个实例。 - 卡片界面只能通过预设项调整,不提供自定义 CSS。
- 3DS 只通过 iframe 浮层承载,不支持弹窗或整页跳转方式。
token/vaultId的获取与刷新由宿主服务端负责。