連携先クライアント連携ガイド(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 には元の 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,
});
}
QR の再取得には onRefresh を指定します。QR の期限が切れ、利用者が再取得を選ぶと実行され、新しい {qr,expiresAt} を返します。
4. 通常認証:openVerify
サーバーで対象の操作を準備してから openVerify を呼び出します。submit で 6 桁のコードを検証し、成功後に 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 | 初回連携では必須。サーバーが返した元の QR JSON 文字列。 |
expiresAt | string | 初回連携では必須で、QR の有効期限は作成から最大 60 分です。通常認証では任意のサーバー操作期限です。 |
onRefresh | ({signal}) => Promise<BindingTicket> | 初回連携では任意。新しい {qr,expiresAt} を取得して返します。 |
authLinkOrigin | string | 初回連携では任意。サービス設定に基づいて QR 内の 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>