跳转到主要内容
本页配合 Agent Elements SDK 指南 使用,指南中说明了各个流程和事件的处理方式。
SDK 运行在宿主页面的浏览器环境。卡片、凭据与 3DS 都由 Clink 托管的 iframe 处理,宿主只接收标识和事件。

安装

new AgentElements(options)

创建 SDK 实例,并解析当前环境对应的 Clink 应用地址。
'sandbox' | 'production'
必填
使用哪个 Clink 应用地址,见 环境映射。
PresetOptions
外观与语言设置,见 预设项。

预设项

'en-US' | 'zh-CN'
默认值:"en-US"
界面语言与 antd locale。
string
默认值:"#1677ff"
组件主色,CSS 颜色值。
number
默认值:"8"
组件圆角,单位 px。
number
默认值:"8"
卡片容器圆角,单位 px。
预设项在 SDK 发送 init 时应用。运行期只能用 setLocale 切换语言;主色和圆角创建后不可更改。

元素凭据

凭据在 createElement 时按元素类型传入:
string
必填
服务端签发的 card-session token(scope card:manage,有效期 1799s)。必填且不能为空;只保存在内存中。
string
必填
服务端签发的一次性会话 id(有效期约 30 分钟)。元素页面用它兑换 vault token,宿主不持有该 token。

方法

AgentElement<T>
创建 type 对应的元素并传入该元素的凭据:paymentMethods 传 { token },vault 传 { vaultId }。一个实例只能创建一个元素,重复调用会抛错;凭据为空也会抛错。元素在调用 mount() 之前不会渲染。
void
更新语言。mount 之前调用会在下一次 init 时下发;mount 之后调用会立即发送 set-locale。
void
卸载元素、关闭已打开的 3DS 浮层、移除消息监听并清空事件订阅。可重复调用。实例销毁后不可复用,createElement、setLocale 都会抛错。

错误

AgentElement

元素由 createElement 创建,事件订阅挂在元素上。
ElementType
元素类型:'paymentMethods' 或 'vault'。
void
仅 paymentMethods 可用。更新元素内的 card-session token:mount 之前调用会在下一次 init 下发;mount 之后调用会发送 set-token 并重新加载卡片数据。空值会抛错。vault 的凭据是一次性 vaultId,不支持刷新。
void
订阅该元素的事件。建议在 mount() 之前注册,避免漏掉事件。
void
取消订阅。
void
挂载 iframe。target 可以是 CSS 选择器或 HTMLElement,容器必须存在。见 挂载选项。
void
移除 wrapper 与 iframe。事件订阅会保留,可以再次挂载;重新挂载会重新加载 iframe。
HTMLIFrameElement | null
返回当前 iframe;未挂载时返回 null。

挂载选项

传给 mount() 的展示开关与主操作按钮外观,只在下一次挂载时生效。选项类型由元素类型决定,传错字段会在编译期报错。

paymentMethods

boolean
默认值:"false"
隐藏加载骨架屏。
boolean
默认值:"false"
隐藏已保存卡片列表。
boolean
默认值:"false"
隐藏删卡入口。
boolean
默认值:"false"
隐藏设为默认卡入口。
AgentElementButtonOptions
主操作按钮外观,见 按钮选项。

vault

boolean
默认值:"false"
隐藏加载骨架屏。
boolean
默认值:"false"
隐藏「选择卡片」标题与副标题。
AgentElementButtonOptions
主操作按钮外观,见 按钮选项。
挂载选项只是展示配置,不是密钥。SDK 会把它们编码进 iframe 地址;不要放入 token 等敏感值。

按钮选项

主操作按钮指元素底部的「添加银行卡」「解锁银行卡」或「继续」按钮。
number
默认值:"40"
按钮高度,单位 px。
number
默认值:"16"
按钮字号,单位 px。
number
默认值:"presetOptions.radius.components"
按钮圆角,单位 px。
未传的字段保持默认值,只需要加高按钮的宿主可以只传 height。非数字或超出区间的值(高度 16–200、字号 8–40、圆角 0–100)会被忽略。卡列表行内的「设为默认」「删除」按钮与失败重试按钮不受影响。

事件

事件按元素划分,事件名与 payload 由元素类型推导。

paymentMethods 事件

vault 事件

error.source 取值: unmount() 不会清除订阅,只有 destroy() 会。

环境映射

environment 必传:接入联调用 sandbox(UAT),上线后用 production。

模块导出

version 由构建时注入。直接引用源码时返回 0.0.0-dev。

类型

构建产物

包不提供 CommonJS 产物。内部的 iframe bridge 会在构建时打入产物,发布后的包没有私有运行时依赖。

Script 标签

通过 <script> 标签加载时,SDK 挂载在全局变量 ClinkAgentElements 下。生产环境请把 @<version> 固定为实际版本号。