一键

One Tap 插件允许用户通过一次轻触使用 Google 的 One Tap API 登录。该插件提供了一种将 One Tap 集成到你的应用中的简单方式，为你处理客户端和服务器端的逻辑。

🌐 The One Tap plugin allows users to log in with a single tap using Google's One Tap API. The plugin provides a simple way to integrate One Tap into your application, handling the client-side and server-side logic for you.

安装

🌐 Installation

添加服务器插件

🌐 Add the Server Plugin

将 One Tap 插件添加到你的身份验证配置中：

🌐 Add the One Tap plugin to your auth configuration:

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

export const auth = betterAuth({
    plugins: [ 
        oneTap(), // Add the One Tap server plugin
    ] 
});

添加客户端插件

🌐 Add the Client Plugin

添加客户端插件，并指定用户登录后或需要额外验证（如双因素认证）时应重定向到的位置。

🌐 Add the client plugin and specify where the user should be redirected after sign-in or if additional verification (like 2FA) is needed.

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

export const authClient = createAuthClient({
  plugins: [
    oneTapClient({
      clientId: "YOUR_CLIENT_ID",
      // Optional client configuration:
      autoSelect: false,
      cancelOnTapOutside: true,
      context: "signin",
      additionalOptions: {
        // Any extra options for the Google initialize method
      },
      // Configure prompt behavior and exponential backoff:
      promptOptions: {
        baseDelay: 1000,   // Base delay in ms (default: 1000)
        maxAttempts: 5     // Maximum number of attempts before triggering onPromptNotification (default: 5)
      }
    })
  ]
});

用法

🌐 Usage

要显示 One Tap 弹出窗口，只需在你的身份验证客户端上调用 oneTap 方法即可：

🌐 To display the One Tap popup, simply call the oneTap method on your auth client:

await authClient.oneTap();

自定义重定向行为

🌐 Customizing Redirect Behavior

默认情况下，登录成功后，插件会将用户直接重定向到 /。你可以按如下方式自定义此行为：

🌐 By default, after a successful login the plugin will hard redirect the user to /. You can customize this behavior as follows:

避免硬重定向

🌐 Avoiding a Hard Redirect

传递带有 onSuccess 回调的 fetchOptions，以在不重新加载页面的情况下处理登录响应：

🌐 Pass fetchOptions with an onSuccess callback to handle the login response without a page reload:

await authClient.oneTap({
  fetchOptions: {
    onSuccess: () => {
      // For example, use a router to navigate without a full reload:
      router.push("/dashboard");
    }
  }
});

指定自定义回调 URL

🌐 Specifying a Custom Callback URL

要在登录后执行跳转到不同页面的硬重定向，请使用 callbackURL 选项：

🌐 To perform a hard redirect to a different page after login, use the callbackURL option:

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

使用指数退避处理提示取消

🌐 Handling Prompt Dismissals with Exponential Backoff

如果用户关闭或跳过提示，插件将根据你配置的 promptOptions 使用指数回退方式重新尝试显示一键提示。

🌐 If the user dismisses or skips the prompt, the plugin will retry showing the One Tap prompt using exponential backoff based on your configured promptOptions.

如果在达到最大尝试次数后仍未成功登录，你可以使用 onPromptNotification 回调来接收通知 - 这样你就可以呈现一个替代的用户界面（例如传统的 Google 登录按钮），以便用户可以手动重新启动该过程：

🌐 If the maximum number of attempts is reached without a successful sign-in, you can use the onPromptNotification callback to be notified—allowing you to render an alternative UI (e.g., a traditional Google Sign-In button) so users can restart the process manually:

await authClient.oneTap({
  onPromptNotification: (notification) => {
    console.warn("Prompt was dismissed or skipped. Consider displaying an alternative sign-in option.", notification);
    // Render your alternative UI here
  }
});

客户选项

🌐 Client Options

• clientId：你的 Google One Tap API 客户端 ID。
• autoSelect：如果用户已经登录，则自动选择账户。默认值为 false。
• cancelOnTapOutside：当用户点击弹窗外部时取消 One Tap 弹窗。要使用此选项，请禁用 promptOptions.fedCM。默认值为 true。
• uxMode：用于 Google One Tap 流程的模式。可以是“popup”或“redirect”。默认值是“popup”。
• context：One Tap API 应该使用的上下文。可以是 "signin"、"signup" 或 "use"。默认值是 "signin"。
• additionalOptions：根据Google身份服务文档传递给Google初始化方法的额外选项。
• promptOptions：提示行为和指数回退的配置：
  • baseDelay：重试的基础延迟时间，单位为毫秒。默认值为1000。
  • maxAttempts：在调用 onPromptNotification 回调之前，最大的提示尝试次数。默认值为 5。
  • fedCM：是否启用联邦凭证管理 (FedCM)支持。默认值为 true。

服务器选项

🌐 Server Options

• disableSignUp：禁用注册选项，仅允许现有用户登录。默认值为 false。
• clientId：可选，如果你的社交提供商配置中未提供客户端 ID，可在此处传入。

授权的 JavaScript 来源

🌐 Authorized JavaScript origins

请确保已在 Google Cloud Console 中为你的客户端 ID 配置了授权的 JavaScript 来源（例如：http://localhost:3000，https://example.com）。这是使用 Google One Tap API 的必需步骤，如果来源未正确设置，该 API 将无法正常工作。

🌐 Ensure you have configured the Authorized JavaScript origins (e.g., http://localhost:3000, https://example.com) for your Client ID in the Google Cloud Console. This is a required step for the Google One Tap API, and it will not function correctly unless your origins are correctly set.