显示“使用 Google 帐号登录”按钮

向您的网站添加“使用 Google 帐号登录”按钮,让用户能够注册或登录您的 Web 应用。您可以使用 HTML 或 JavaScript 呈现该按钮和属性,以便自定义按钮的形状、大小、文字和主题背景。

个性化的登录按钮。

用户选择 Google 帐号并表示同意后,Google 会使用 JSON Web 令牌 (JWT) 共享用户个人资料。如需简要了解登录和用户体验期间所涉及的步骤,请参阅工作原理了解个性化按钮可查看影响按钮向用户显示方式的不同条件和状态。

前提条件

在将该按钮添加到登录页面之前,请完成以下步骤:

按钮呈现

如需显示“使用 Google 账号登录”按钮,您可以选择 HTML 或 JavaScript 在登录页面上呈现该按钮:

HTML

使用 HTML 呈现登录按钮,并将 JWT 返回到平台的登录端点。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async></script>
    <div id="g_id_onload"
        data-client_id="YOUR_GOOGLE_CLIENT_ID"
        data-login_uri="https://your.domain/your_login_endpoint"
        data-auto_prompt="false">
    </div>
    <div class="g_id_signin"
        data-type="standard"
        data-size="large"
        data-theme="outline"
        data-text="sign_in_with"
        data-shape="rectangular"
        data-logo_alignment="left">
    </div>
  <body>
</html>

具有 g_id_signin 类的元素会呈现为“使用 Google 账号登录”按钮。该按钮由数据属性中提供的参数进行自定义。

如需在同一页面上显示“使用 Google 账号登录”按钮和 Google 一键快捷功能,请移除 data-auto_prompt="false"。建议执行此操作,以减少麻烦,提高登录率。

如需查看数据属性的完整列表,请参阅 g_id_signin 参考页面

JavaScript

使用 JavaScript 呈现登录按钮,并将 JWT 返回给浏览器的 JavaScript 回调处理程序。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async></script>
    <script>
      function handleCredentialResponse(response) {
        console.log("Encoded JWT ID token: " + response.credential);
      }
      window.onload = function () {
        google.accounts.id.initialize({
          client_id: "YOUR_GOOGLE_CLIENT_ID"
          callback: handleCredentialResponse
        });
        google.accounts.id.renderButton(
          document.getElementById("buttonDiv"),
          { theme: "outline", size: "large" }  // customization attributes
        );
        google.accounts.id.prompt(); // also display the One Tap dialog
      }
    </script>
    <div id="buttonDiv"></div>
  </body>
</html>

指定为 renderButton 的第一个参数的元素显示为“使用 Google 帐号登录”按钮。在此示例中,buttonDiv 用于在网页上呈现按钮。您可以使用 renderButton 的第二个参数中指定的属性自定义该按钮。

为了尽可能减少用户摩擦,系统会调用 google.accounts.id.prompt(),以将“一键快捷功能”显示为使用按钮注册或登录的另一种替代方案。

GIS 库会解析 HTML 文档,以获取 ID 属性设为 g_id_onload 的元素或包含 g_id_signin 的类属性。如果找到了匹配的元素,那么无论您是否也使用 JavaScript 呈现了该按钮,系统都会使用 HTML 呈现该按钮。为避免两次显示该按钮,请避免在 HTML 网页中包含与这些名称匹配的 HTML 元素(如果参数可能存在冲突)。

按钮语言

按钮语言由浏览器的默认语言或 Google 会话用户的偏好设置自动确定。您也可以手动选择语言,方法是在加载库时将 hl 参数和语言代码添加到 src 指令,以及在 HTML 或 JavaScript 的语言区域中添加可选的数据语言区域或语言区域参数 data-locale

HTML

以下代码段展示了如何通过将 hl 参数添加到客户端库网址并将 data-locale 属性设置为法语来以法语显示按钮语言:

<script src="https://accounts.google.com/gsi/client?hl=fr" async></script>
<div class="g_id_signin" data-locale="fr">
</div>

JavaScript

以下代码段展示了如何以法语显示按钮语言,方法是向客户端库网址添加 hl 参数,并调用 google.accounts.id.renderButton 方法(将 locale 参数设为法语):

<script src="https://accounts.google.com/gsi/client?hl=fr" async></script>
<script>
  google.accounts.id.renderButton(
    document.getElementById("buttonDiv"),
    { locale: "fr" }
  );
</script>

凭据处理

征得用户同意后,Google 会将 JSON Web 令牌 (JWT) 凭据(称为 ID 令牌)返回给用户浏览器,或直接返回到由您的平台托管的登录端点。

您选择接收 JWT 的位置取决于您是使用 HTML 还是 JavaScript 呈现按钮,以及是否使用了弹出或重定向用户体验模式。

使用 popup 用户体验模式会在弹出式窗口中执行登录用户体验流程。这种模式通常对用户体验的干扰较小,并且是默认的用户体验模式。

使用以下代码呈现按钮时:

HTML

您可以设置以下任一项:

  • data-callback 以将 JWT 返回至回调处理程序,或者
  • data-login_uri,供 Google 使用 POST 请求将 JWT 直接发送到您的登录端点。

如果同时设置了这两个值,则 data-callback 优先于 data-login_uri。在使用回调处理程序进行调试时,同时设置两个值可能会有帮助。

JavaScript

您必须指定 callback。在 JavaScript 中呈现按钮时,弹出式模式不支持重定向。如果设置此参数,系统会忽略 login_uri

如需详细了解如何在 JS 回调处理程序中解码 JWT,请参阅处理返回的凭据响应

重定向模式

使用 redirect 用户体验模式时,系统会使用用户浏览器的完整页面重定向来执行登录用户体验流程,而 Google 则会使用 POST 请求将 JWT 直接返回到您的登录端点。这种登录方式通常对用户而言更具干扰性,但被认为是最安全的登录方法。

使用以下代码呈现按钮时:

  • HTML(可选)将 data-login_uri 设置为登录端点的 URI。
  • JavaScript 可以选择将 login_uri 设置为登录端点的 URI。

如果您未提供值,Google 会将 JWT 返回到当前页面的 URI。

您的登录端点 URI

设置 data-login_urilogin_uri 时,请使用 HTTPS 和绝对 URI。 例如 https://example.com/path

只有在开发期间使用 localhost 时,才允许使用 HTTP:http://localhost/path

如需查看 Google 的要求和验证规则的完整说明,请参阅使用安全的 JavaScript 来源和重定向 URI