接入方客户端接入指南(Web SDK)
在接入方客户端中接入首次绑定与验证码验证;验证码由接入方服务端验证并完成业务处理。
1. 安装
npm install @auth-link/web@latest
2. 实现 submit 回调
使用网站现有的请求方法,将验证码提交到服务端。示例中的 verifyRequest 由你的项目提供。
import type { Submit } from '@auth-link/web';
export function createSubmit(
verifyRequest: (
data: { passcode: string },
options: { signal: AbortSignal },
) => Promise<void>,
): Submit {
return async (passcode, { signal }) => {
await verifyRequest({ passcode }, { signal });
};
}
submit(passcode,{signal}) 返回 Promise<void>。验证码使用字符串以保留前导零;服务端验证并完成业务后正常结束,请求或业务失败时抛出错误。
将 signal 传给请求方法,以支持关闭弹窗或卸载时取消等待。结果不明时,使用原操作和原幂等键重试。
3. 首次绑定:openBind
先向服务端获取 {qr,expiresAt},再调用 openBind。qr 使用服务端返回的原始二维码 JSON 内容,expiresAt 使用原始截止时间。用户扫码并提交验证码后,由服务端完成绑定。
import { openBind } from '@auth-link/web';
import type { BindingTicket, BindOptions, Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function bindAccount(
ticket: BindingTicket,
submit: Submit,
onRefresh?: BindOptions['onRefresh'],
) {
return openBind({
qr: ticket.qr,
expiresAt: ticket.expiresAt,
submit,
onRefresh,
});
}
需要重新获取二维码时,提供 onRefresh 回调。它在二维码过期、用户点击重新获取时执行,返回新的 {qr,expiresAt}。
4. 日常验证:openVerify
服务端准备好本次待验证操作后调用 openVerify。通过 submit 验证用户输入的六位码,成功后使用 onSuccess 更新页面。
import { openVerify } from '@auth-link/web';
import type { Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function verifyAction(submit: Submit, onSuccess?: () => void) {
return openVerify({ submit, onSuccess });
}
5. 参数与回调
| 参数 | 类型 | 说明 |
|---|---|---|
submit | (passcode, {signal}) => Promise<void> | 必填。提交验证码并等待服务端完成验证和业务处理。 |
qr | string | 首次绑定必填。服务端返回的原始二维码 JSON 字符串。 |
expiresAt | string | 首次绑定必填,二维码从创建起最多有效 60 分钟;日常验证可选,表示服务端操作的截止时间。 |
onRefresh | ({signal}) => Promise<BindingTicket> | 首次绑定可选。重新获取绑定凭据并返回 {qr,expiresAt}。 |
authLinkOrigin | string | 首次绑定可选。校验二维码中的 AuthLink 服务来源,取自你的服务配置。 |
onSuccess | () => void | Promise<void> | 可选。验证成功、弹窗关闭后更新界面。 |
onError | (error: Error) => void | 可选。接收请求或业务错误。 |
onClose | () => void | 可选。用户关闭弹窗或调用 close() 时执行。 |
onExpired | () => void | Promise<void> | 可选。expiresAt 到期时执行。 |
locale | Locale | 可选。设置界面语言,默认 zh-CN。 |
语言代码:zh-CN、zh-TW、en、ja、bn、es、fil、hi、id、ms、pt、th、vi。
6. 弹窗方法
openBind 和 openVerify 都返回 AuthLinkModal,可调用以下方法。
| 方法 | 说明 |
|---|---|
close() | 关闭弹窗,取消等待,并触发 onClose。 |
destroy() | 销毁弹窗并取消等待,静默清理。 |
retry() | 清除错误并允许用户重新提交。 |
setLocale(locale) | 切换界面语言并保留已输入的验证码。 |
7. React / Vue
组件参数与 JavaScript 方法相同。首次绑定使用 AuthLinkBind,日常验证使用 AuthLinkVerify。成功或关闭后卸载组件;Vue 通过 success、close、error、expired 事件通知结果,onRefresh 使用函数属性。
React
"use client";
import { AuthLinkBind, AuthLinkVerify } from '@auth-link/web/react';
import type { BindingTicket, Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function Bind({ ticket, submit, onSuccess, onClose }: {
ticket: BindingTicket; submit: Submit;
onSuccess: () => void; onClose: () => void;
}) {
return <AuthLinkBind {...ticket} submit={submit}
onSuccess={onSuccess} onClose={onClose} />;
}
export function Verify({ submit, onSuccess, onClose }: {
submit: Submit; onSuccess: () => void; onClose: () => void;
}) {
return <AuthLinkVerify submit={submit}
onSuccess={onSuccess} onClose={onClose} />;
}
Vue
<script setup lang="ts">
import { AuthLinkVerify, AuthLinkBind } from '@auth-link/web/vue';
import type { Submit, BindingTicket } from '@auth-link/web';
import '@auth-link/web/styles.css';
defineProps<{ submit: Submit; ticket?: BindingTicket }>();
const emit = defineEmits<{ success: []; close: [] }>();
</script>
<template>
<AuthLinkBind v-if="ticket" v-bind="ticket" :submit="submit"
@success="emit('success')" @close="emit('close')" />
<AuthLinkVerify v-else :submit="submit"
@success="emit('success')" @close="emit('close')" />
</template>