警告:此数据是根据Google用户数据政策提供的。请查看并遵守政策。否则可能会导致项目或帐户被暂停。

使用 Google JavaScript API 参考登录

此参考页面描述了登录 JavaScript API。您可以使用此 API 在您的网页上显示一键提示或使用 Google 登录按钮。

方法:google.accounts.id.initialize

google.accounts.id.initialize方法初始化在与谷歌基于客户端的配置对象。请参阅以下方法的代码示例:

google.accounts.id.initialize(IdConfiguration)

下面的代码示例实现google.accounts.id.initialize方法用onload功能:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

数据类型:IdConfiguration

下表列出的字段和所述的说明IdConfiguration数据类型:

场地
client_id您的应用程序的客户端 ID
auto_select启用自动选择。
callback处理 ID 令牌的 JavaScript 函数。谷歌一个水龙头和在与谷歌按钮popup UX模式下使用此属性。
login_uri您的登录端点的 URL。将在与谷歌按钮redirect UX模式使用此属性。
native_callback处理密码凭据的 JavaScript 函数。
cancel_on_tap_outside如果用户在提示之外单击,则取消提示。
prompt_parent_id One Tap 提示容器元素的DOM ID
nonce ID 令牌的随机字符串
context One Tap 提示中的标题和单词
state_cookie_domain如果您需要在父域及其子域中调用 One Tap,请将父域传递给此字段,以便使用单个共享 cookie。
ux_mode使用 Google 按钮登录的用户体验流程
allowed_parent_origin允许嵌入中间 iframe 的来源。如果此字段出现,One Tap 将在中间 iframe 模式下运行。
intermediate_iframe_close_callback当用户手动关闭 One Tap 时,覆盖默认的中间 iframe 行为。

客户编号

此字段是您的应用程序的客户端 ID,可在 Google Developers Console 中找到并创建。有关详细信息,请参阅下表:

类型必需的例子
细绳是的client_id: "CLIENT_ID.apps.googleusercontent.com"

自动选择

当之前只有一个 Google 会话批准您的应用程序时,此字段确定是否在没有任何用户交互的情况下自动返回 ID 令牌。默认值是false 。有关详细信息,请参阅下表:

类型必需的例子
布尔值可选的auto_select: true

打回来

此字段是处理从 One Tap 提示或弹出窗口返回的 ID 令牌的 JavaScript 函数。如果谷歌一个水龙头或在与谷歌按钮就需要这个属性popup使用UX模式。有关详细信息,请参阅下表:

类型必需的例子
功能需要一个水龙头和popup UX模式callback: handleResponse

登录_uri

此属性是您的登录端点的 URI。如果当前页面是您的登录页面,则可以省略,在这种情况下,凭据默认发布到此页面。

当用户单击“使用 Google 登录”按钮并使用重定向 UX 模式时,ID 令牌凭据响应将发布到您的登录端点。

有关详细信息,请参阅下表:

类型可选的例子
网址默认为当前页面的 URI,或您指定的值。
只有当使用ux_mode: "redirect"设置。
login_uri="https://www.example.com/login"

您的登录端点必须处理包含POST请求credential与体内的ID令牌值的关键。

以下是对您的登录端点的示例请求:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

native_callback

此字段是处理从浏览器的本机凭据管理器返回的密码凭据的 JavaScript 函数的名称。有关详细信息,请参阅下表:

类型必需的例子
功能可选的native_callback: handleResponse

cancel_on_tap_outside

此字段设置如果用户在提示之外单击,是否取消 One Tap 请求。默认值是true 。如果将值设置为您可以禁用它false 。有关详细信息,请参阅下表:

类型必需的例子
布尔值可选的cancel_on_tap_outside: false

prompt_parent_id

此属性设置容器元素的 DOM ID。如果未设置,则窗口右上角会显示一键提示。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的prompt_parent_id: 'parent_id'

随机数

此字段是 ID 令牌用于防止重放攻击的随机字符串。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的nonce: "biaqbm70g23"

Nonce 长度受限于您的环境支持的最大 JWT 大小,以及各个浏览器和服务器 HTTP 大小的限制。

语境

此字段更改 One Tap 提示中的标题和消息文本。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的context: "use"

下表列出了可用的上下文及其说明:

语境
signin “使用谷歌登录”
signup “使用谷歌注册”
use “与谷歌一起使用”

如果您需要在父域及其子域中显示 One Tap,请将父域传递给此字段,以便使用单个共享状态 cookie。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的state_cookie_domain: "example.com"

ux_mode

使用此字段设置“使用 Google 登录”按钮使用的用户体验流程。默认值是popup 。此属性对 OneTap UX 没有影响。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的ux_mode: "redirect"

下表列出了可用的 UX 模式及其说明。

用户体验模式
popup在弹出窗口中执行登录 UX 流程。
redirect通过整页重定向执行登录 UX 流程。

allowed_pa​​rent_origin

允许嵌入中间 iframe 的来源。如果此字段出现,One Tap 将在中间 iframe 模式下运行。有关详细信息,请参阅下表:

类型必需的例子
字符串或字符串数​​组可选的allowed_parent_origin: "https://example.com"

下表列出了支持的值类型及其说明。

值类型
string单个域 URI。 “https://example.com”
string array域 URI 的数组。 ["https://news.example.com", "https://local.example.com"]

还支持通配符前缀。例如, "https://*.example.com"将匹配example.com及其子域各级(如news.example.comlogin.news.example.com )。使用通配符时要记住的事情:

  • 模式字符串不能仅由通配符和顶级域组成。例如https://*.comhttps://*.co.uk无效;如上所述, "https://*.example.com"将匹配example.com及其子域。您还可以使用数组来表示 2 个不同的域。例如, ["https://example1.com", "https://*.example2.com"]将匹配域example1.comexample2.com和子域的example2.com
  • 通配符域必须以安全的 https:// 方案开头。 "*.example.com"将被视为无效。

如果值allowed_parent_origin字段无效,中间IFRAME模式的一个抽头初始化会失败,并停止。

middle_iframe_close_callback

当用户通过点击 One Tap UI 中的“X”按钮手动关闭 One Tap 时,覆盖默认的中间 iframe 行为。默认行为是立即从 DOM 中删除中间 iframe。

所述intermediate_iframe_close_callback字段只需要在中间的iframe模式的效果。而且它只影响中间 iframe,而不是 One Tap iframe。在调用回调之前删除一键用户界面。

类型必需的例子
功能可选的intermediate_iframe_close_callback: logBeforeClose

方法:google.accounts.id.prompt

google.accounts.id.prompt方法显示后的一个抽头提示或浏览器的本地凭证管理器initialize()方法被调用。请参阅以下方法的代码示例:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

通常情况下, prompt()方法被调用在页面加载。由于谷歌端的会话状态和用户设置,一键提示UI可能不会显示。要获得不同时刻的 UI 状态通知,请传递一个函数来接收 UI 状态通知。

在以下时刻触发通知:

  • 显示时刻:后会出现此prompt()方法被调用。通知包含一个布尔值来指示是否显示 UI。
  • 跳过的时刻:当一个水龙头提示是由自动关闭取消,手动取消,或当谷歌未能出具的凭证,比如当选择的对话签署的谷歌了出现这种情况。

    在这些情况下,我们建议您继续使用下一个身份提供商(如果有)。

  • 驳回的时刻:这发生在谷歌成功地检索凭证或用户想要停止凭据检索流程。例如,当用户在登录对话框中开始输入自己的用户名和密码,你可以调用google.accounts.id.cancel()方法来关闭一个抽头提示,并引发解雇的时刻。

以下代码示例实现了跳过的时刻:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

数据类型:PromptMomentNotification

所述的下表列出的方法和说明PromptMomentNotification数据类型:

方法
isDisplayMoment()这是显示时刻的通知吗?
isDisplayed()这是一个显示时刻的通知,并显示UI?
isNotDisplayed()此通知是否为显示时刻,而 UI 未显示?
getNotDisplayedReason()

未显示 UI 的详细原因。以下是可能的值:

  • browser_not_supported
  • invalid_client
  • missing_client_id
  • opt_out_or_no_session
  • secure_http_required
  • suppressed_by_user
  • unregistered_origin
  • unknown_reason
isSkippedMoment()这个通知是跳过的时刻吗?
getSkippedReason()

跳过时刻的详细原因。以下是可能的值:

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
isDismissedMoment()此通知是针对已解除时刻的通知吗?
getDismissedReason()

解雇的详细原因。以下是可能的值:

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

为 moment 类型返回一个字符串。以下是可能的值:

  • display
  • skipped
  • dismissed

数据类型:凭据响应

当你的callback被调用函数, CredentialResponse对象作为参数传递。下表列出了凭证响应对象中包含的字段:

场地
credential此字段是返回的 ID 令牌。
select_by此字段设置选择凭据的方式。

凭据

此字段是作为 base64 编码的 JSON Web 令牌 (JWT) 字符串的 ID 令牌。

解码,智威汤逊看起来像下面的例子:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

sub字段包含谷歌帐户的全局唯一标识符。

使用emailemail_verifiedhd字段,如果谷歌的主机就可以判断是权威性的电子邮件地址。在 Google 具有权威性的情况下,当前已知用户是合法帐户所有者。

谷歌权威的案例:

  • email有一个@gmail.com后缀,这是一个Gmail帐户。
  • email_verified是真实的, hd设置,这是G套房帐户。

用户无需使用 Gmail 或 G Suite 即可注册 Google 帐户。当email不包含@gmail.com后缀和hd不存在谷歌是不具有权威性和密码或其他挑战的方法,建议以验证用户。 email_verfied作为谷歌最初验证创建谷歌帐户时,可能已在改变,不过第三方电子邮件帐户所有权的用户也可以是真实的。

select_by

下表列出了可能的值select_by场。与会话和同意状态一起使用的按钮类型用于设置值,

  • 用户按下“一键”或“使用 Google 登录”按钮或使用非接触式自动登录过程。

  • 找到了现有会话,或者用户选择并登录了 Google 帐户以建立新会话。

  • 在与您的应用程序共享 ID 令牌凭据之前,用户要么

    • 按下确认按钮以同意他们共享凭据,或
    • 之前已同意并使用“选择一个帐户”来选择一个 Google 帐户。

此字段的值设置为以下类型之一,

价值描述
auto使用先前已同意共享凭据的现有会话的用户的自动登录。
user具有先前已授予同意的现有会话的用户按下一键“继续为”按钮以共享凭据。
user_1tap具有现有会话的用户按下 One Tap 'Continue as' 按钮以授予同意并共享凭据。仅适用于 Chrome v75 及更高版本。
user_2tap没有现有会话的用户按下 One Tap 'Continue as' 按钮选择一个帐户,然后按下弹出窗口中的 Confirm 按钮以授予同意并共享凭据。适用于非基于 Chromium 的浏览器。
btn具有先前同意的现有会话的用户按下“使用 Google 登录”按钮并从“选择帐户”中选择一个 Google 帐户以共享凭据。
btn_confirm具有现有会话的用户按下“使用 Google 登录”按钮并按下“确认”按钮以授予同意并共享凭据。
btn_add_session先前未授予同意的现有会话的用户按下“使用 Google 登录”按钮选择 Google 帐户并共享凭据。
btn_confirm_add_session没有现有会话的用户首先按“使用 Google 登录”按钮选择 Google 帐户,然后按“确认”按钮同意并共享凭据。

方法:google.accounts.id.renderButton

google.accounts.id.renderButton方法呈现一个在与谷歌按钮,在您的网页。

请参阅以下方法的代码示例:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

数据类型:GsiButtonConfiguration

下表列出的字段和所述的说明GsiButtonConfiguration数据类型:

属性
type按钮类型:图标或标准按钮。
theme按钮主题。例如,filled_blue 或filled_black。
size按钮大小。例如,小或大。
text按钮文本。例如,“使用 Google 登录”或“使用 Google 注册”。
shape按钮形状。例如,矩形或圆形。
logo_alignment Google 徽标对齐方式:左对齐或居中对齐。
width按钮宽度,以像素为单位。
locale如果设置,则呈现按钮语言。

属性类型

以下部分包含有关每个属性类型的详细信息和示例。

类型

按钮类型。默认值是standard

有关详细信息,请参阅下表:

类型必需的例子
细绳是的type: "icon"

下表列出了可用的按钮类型及其说明:

类型
standard带有文本或个性化信息的按钮:
icon一个没有文字的图标按钮:

主题

按钮主题。默认值是outline 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的theme: "filled_blue"

下表列出了可用的主题及其说明:

主题
outline标准按钮主题:
filled_blue蓝色填充按钮主题:
filled_black黑色填充按钮主题:

尺寸

按钮大小。默认值是large 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的size: "small"

下表列出了可用的按钮大小及其说明:

尺寸
large一个大按钮:
一个大的标准按钮一个大图标按钮一个大的、个性化的按钮
medium一个中等大小的按钮:
中等标准按钮中等图标按钮
small一个小按钮:
一个小按钮一个小图标按钮

文本

按钮文本。默认值是signin_with 。有针对具有不同的图标按钮的文本,没有视觉上的差异text属性。唯一的例外是当为了屏幕可访问性而读取文本时。

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的text: "signup_with"

下表列出了可用的按钮文本及其说明:

文本
signin_with按钮文本为“使用 Google 登录”:
signup_with按钮文字是“Sign up with Google”:
continue_with按钮文字是“Continue with Google”:
signup_with按钮文本为“登录”:

形状

按钮形状。默认值是rectangular 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的shape: "rectangular"

下表列出了可用的按钮形状及其说明:

形状
rectangular矩形按钮。如果用于icon按钮式,那么它的同square
pill丸状按钮。如果用于icon按钮式,那么它是一样的circle
circle圆形按钮。如果用于standard按钮式,那么它是一样的pill
square方形按钮。如果用于standard按钮式,那么它是一样的rectangular

logo_alignment

Google 徽标的对齐方式。默认值是left 。此属性仅适用于standard按键式。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的logo_alignment: "center"

下表列出了可用的路线及其说明:

logo_alignment
left左对齐 Google 徽标。
center居中对齐 Google 徽标。

宽度

最小按钮宽度,以像素为单位。最大宽度为 400 像素。

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的width: 400

语言环境

按钮文本的预设语言环境。如果未设置,则使用浏览器的默认区域设置或 Google 会话用户的首选项。因此,不同的用户可能会看到不同版本的本地化按钮,并且可能具有不同的大小。

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的locale: "zh_CN"

数据类型:凭证

当你的native_callback被调用函数, Credential对象作为参数传递。下表列出了对象中包含的字段:

场地
id标识用户。
password密码

方法:google.accounts.id.disableAutoSelect

当用户退出你的网站,你需要调用方法google.accounts.id.disableAutoSelect记录在cookie中的地位。这可以防止 UX 死循环。请参阅该方法的以下代码片段:

google.accounts.id.disableAutoSelect()

下面的代码示例实现google.accounts.id.disableAutoSelect方法与onSignout()函数:

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

方法:google.accounts.id.storeCredential

此方法是在一个简单的包装store()浏览器的原生凭据管理器API的方法。因此,它只能用于存储密码凭证。请参阅以下方法的代码示例:

google.accounts.id.storeCredential(Credential, callback)

下面的代码示例实现google.accounts.id.storeCredential方法与onSignIn()函数:

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

方法:google.accounts.id.cancel

如果从信赖方 DOM 中删除提示,则可以取消 One Tap 流程。如果已选择凭证,则忽略取消操作。请参阅以下方法的代码示例:

google.accounts.id.cancel()

下面的代码示例实现google.accounts.id.cancel()方法用onNextButtonClicked()函数:

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

库加载回调:onGoogleLibraryLoad

你可以注册一个onGoogleLibraryLoad回调。在 Sign In With Google JavaScript 库加载后,它会收到通知:

window.onGoogleLibraryLoad = () => {
    ...
};

这个回调是只为一个快捷方式window.onload回调。行为上没有差异。

下面的代码示例实现一个onGoogleLibraryLoad回调:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

方法:google.accounts.id.revoke

google.accounts.id.revoke方法撤销用于共享令牌指定用户该ID的OAuth的授权。看到了该方法的下面的代码片断: google.accounts.id.revoke(hint, callback)

范围类型描述
hint细绳用户 Google 帐户的电子邮件地址或唯一 ID。该ID是在sub所述的属性证书有效载荷。
callback功能可选RevocationResponse处理程序。

以下代码示例示出了如何使用revoke与ID方法。

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

数据类型:撤销响应

当你的callback被调用函数, RevocationResponse对象作为参数传递。下表列出了吊销响应对象中包含的字段:

场地
successful该字段是方法调用的返回值。
error该字段可选地包含详细的错误响应消息。

成功的

如果撤消方法调用成功,则此字段是设置为 true 或失败时设置为 false 的布尔值。

错误

此字段是一个字符串值,如果 revoke 方法调用失败,则包含详细的错误消息,成功时未定义。