一键

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.】