接入方客戶端接入指南(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>