One Tap

One Tap 플러그인을 사용하면 사용자가 Google의 One Tap API를 사용하여 한 번의 탭으로 로그인할 수 있습니다. 이 플러그인은 클라이언트 측과 서버 측 로직을 처리하여 One Tap을 애플리케이션에 통합하는 간단한 방법을 제공합니다.

설치

서버 플러그인 추가

auth 구성에 One Tap 플러그인을 추가합니다:

import { betterAuth } from "better-auth";
import { oneTap } from "better-auth/plugins"; 

export const auth = betterAuth({
    plugins: [ 
        oneTap(), // One Tap 서버 플러그인 추가
    ] 
});

클라이언트 플러그인 추가

클라이언트 플러그인을 추가하고 로그인 후 사용자가 리디렉션될 위치나 추가 검증(2FA 등)이 필요한 경우를 지정합니다.

import { createAuthClient } from "better-auth/client";
import { oneTapClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    oneTapClient({
      clientId: "YOUR_CLIENT_ID",
      // 선택적 클라이언트 구성:
      autoSelect: false,
      cancelOnTapOutside: true,
      context: "signin",
      additionalOptions: {
        // Google initialize 메서드를 위한 추가 옵션
      },
      // 프롬프트 동작 및 지수 백오프 구성:
      promptOptions: {
        baseDelay: 1000,   // 기본 지연 시간(밀리초) (기본값: 1000)
        maxAttempts: 5     // onPromptNotification을 트리거하기 전 최대 시도 횟수 (기본값: 5)
      }
    })
  ]
});

사용법

One Tap 팝업을 표시하려면 auth 클라이언트에서 oneTap 메서드를 호출하기만 하면 됩니다:

await authClient.oneTap();

리디렉션 동작 사용자 정의

기본적으로 성공적인 로그인 후 플러그인은 사용자를 /로 하드 리디렉션합니다. 다음과 같이 이 동작을 사용자 정의할 수 있습니다:

하드 리디렉션 방지

페이지 새로고침 없이 로그인 응답을 처리하려면 onSuccess 콜백과 함께 fetchOptions를 전달합니다:

await authClient.oneTap({
  fetchOptions: {
    onSuccess: () => {
      // 예를 들어, 전체 새로고침 없이 라우터를 사용하여 탐색:
      router.push("/dashboard");
    }
  }
});

사용자 정의 콜백 URL 지정

로그인 후 다른 페이지로 하드 리디렉션하려면 callbackURL 옵션을 사용합니다:

await authClient.oneTap({
  callbackURL: "/dashboard"
});

지수 백오프를 사용한 프롬프트 해제 처리

사용자가 프롬프트를 해제하거나 건너뛰면 플러그인은 구성된 promptOptions를 기반으로 지수 백오프를 사용하여 One Tap 프롬프트 표시를 재시도합니다.

성공적인 로그인 없이 최대 시도 횟수에 도달하면 onPromptNotification 콜백을 사용하여 알림을 받을 수 있으며, 사용자가 프로세스를 수동으로 다시 시작할 수 있도록 대체 UI(예: 기존 Google 로그인 버튼)를 렌더링할 수 있습니다:

await authClient.oneTap({
  onPromptNotification: (notification) => {
    console.warn("프롬프트가 해제되거나 건너뛰었습니다. 대체 로그인 옵션을 표시하는 것을 고려하세요.", notification);
    // 여기에서 대체 UI를 렌더링합니다
  }
});

클라이언트 옵션

• clientId: Google One Tap API의 클라이언트 ID입니다.
• autoSelect: 사용자가 이미 로그인한 경우 계정을 자동으로 선택합니다. 기본값은 false입니다.
• context: One Tap API를 사용해야 하는 컨텍스트입니다 (예: "signin"). 기본값은 "signin"입니다.
• cancelOnTapOutside: 사용자가 외부를 탭할 때 One Tap 팝업을 취소합니다. 기본값은 true입니다.
• additionalOptions: Google Identity Services 문서에 따라 Google의 initialize 메서드에 전달할 추가 옵션입니다.
• promptOptions: 프롬프트 동작 및 지수 백오프 구성:
• baseDelay: 재시도를 위한 기본 지연 시간(밀리초)입니다. 기본값은 1000입니다.
• maxAttempts: onPromptNotification 콜백을 호출하기 전 최대 프롬프트 시도 횟수입니다. 기본값은 5입니다.

서버 옵션

• disableSignUp: 가입 옵션을 비활성화하여 기존 사용자만 로그인할 수 있도록 합니다. 기본값은 false입니다.
• ClientId: 소셜 provider 구성에 제공되지 않은 경우 여기에서 선택적으로 클라이언트 ID를 전달합니다.