警告:此數據是根據Google用戶數據政策提供的。請查看並遵守政策。否則可能會導致項目或帳戶被暫停。

使用 Google HTML API 參考登錄

此參考頁面介紹了使用 Google HTML 數據屬性登錄 API。您可以使用 API 在您的網頁上顯示一鍵提示或使用 Google 登錄按鈕。

ID 為“g_id_onload”的元素

您可以在任何可見或不可見元素,如把在與谷歌的數據屬性<div><span>唯一的要求是該元件ID被設置為g_id_onload 。不要將此 ID 放在多個元素上。

數據屬性

下表列出了數據屬性及其說明:

屬性
data-client_id您的應用程序的客戶端 ID
data-auto_prompt顯示谷歌一鍵。
data-auto_select在 Google One Tap 上啟用自動選擇。
data-login_uri您的登錄端點的 URL
data-callback JavaScript ID 令牌處理函數名稱
data-native_login_uri您的密碼憑證處理程序端點的 URL
data-native_callback JavaScript 密碼憑據處理函數名稱
data-native_id_param為參數名稱credential.id
data-native_password_param為參數名稱credential.password
data-cancel_on_tap_outside如果用戶在提示之外單擊,則控制是否取消提示。
data-prompt_parent_id One Tap 提示容器元素的DOM ID
data-skip_prompt_cookie如果指定的 cookie 具有非空值,則跳過一次點擊。
data-nonce ID 令牌的隨機字符串
data-context One Tap 提示中的標題和單詞
data-moment_callback提示UI狀態通知監聽器的函數名
data-state_cookie_domain如果您需要在父域及其子域中調用 One Tap,請將父域傳遞給此屬性,以便使用單個共享 cookie。
data-ux_mode使用 Google 按鈕登錄的用戶體驗流程
data-allowed_parent_origin允許嵌入中間 iframe 的來源。如果此屬性存在,One Tap 將在中間 iframe 模式下運行。
data-intermediate_iframe_close_callback當用戶手動關閉 One Tap 時,覆蓋默認的中間 iframe 行為。

屬性類型

以下部分包含有關每個屬性類型和示例的詳細信息。

數據客戶端_id

此屬性是您應用的客戶端 ID,可在 Google Developers Console 中找到並創建。有關詳細信息,請參閱下表:

類型必需的例子
細繩是的data-client_id="CLIENT_ID.apps.googleusercontent.com"

數據自動提示

該屬性決定是否顯示一鍵。默認值是true 。當這個值是谷歌的一個水龍頭將不會顯示false 。有關詳細信息,請參閱下表:

類型必需的例子
布爾值可選的data-auto_prompt="true"

數據自動選擇

如果只有一個 Google 會話批准了您的應用程序,則此屬性確定是否在沒有任何用戶交互的情況下自動返回 ID 令牌。默認值是false 。有關詳細信息,請參閱下表:

類型必需的例子
布爾值可選的data-auto_select="true"

數據登錄_uri

此屬性是您的登錄端點的 URI。如果當前頁面是您的登錄頁面,則可以省略,在這種情況下,憑據默認發佈到此頁面。

當未定義回調函數並且用戶單擊“使用 Google 登錄”或“一鍵登錄”按鈕或發生自動簽名時,ID 令牌憑據響應將發佈到您的登錄端點。

有關詳細信息,請參閱下表:

類型可選的例子
網址默認為當前頁面的 URI,或您指定的值。
當被忽略的data-ux_mode="popup"data-callback設置。
data-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

數據回調

此屬性是處理返回的 ID 令牌的 JavaScript 函數的名稱。有關詳細信息,請參閱下表:

類型必需的例子
細繩如果需要的data-login_uri未設置。 data-callback="handleToken"

其中的data-login_uridata-callback屬性可能被使用。這取決於以下組件和 UX 模式配置:

  • data-login_uri屬性是必需的在與谷歌按鈕redirect UX模式,而忽略了data-callback屬性。

  • 其中這兩個屬性必須為谷歌一個水龍頭和谷歌登錄按鈕來設置popup UX模式。如果兩者都設置時, data-callback屬性具有更高的優先級。

HTML API 不支持命名空間中的 JavaScript 函數。相反,使用沒有命名空間的全局 JavaScript 函數。例如,使用mylibCallback代替mylib.callback

data-native_login_uri

此屬性是您的密碼憑據處理程序端點的 URL。如果設置無論是data-native_login_uri屬性或data-native_callback屬性,JavaScript庫回落到原始憑據管理器時,沒有谷歌的會話。你不允許設置兩個data-native_callbackdata-native_login_uri屬性。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-login_uri="https://www.example.com/password_login"

數據-native_callback

此屬性是處理從瀏覽器的本機憑據管理器返回的密碼憑據的 JavaScript 函數的名稱。如果設置無論是data-native_login_uri屬性或data-native_callback屬性,JavaScript庫回落到原始憑據管理器時,沒有谷歌的會話。不允許你設置這兩個data-native_callbackdata-native_login_uri 。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-native_callback="handlePasswordCredential"

HTML API 不支持命名空間中的 JavaScript 函數。相反,使用沒有命名空間的全局 JavaScript 函數。例如,使用mylibCallback代替mylib.callback

data-native_id_param

當您提交密碼憑證密碼憑證處理終端,你可以指定參數名稱credential.id場。默認名稱為email 。有關詳細信息,請參閱下表:

類型必需的例子
網址可選的data-native_id_param="user_id"

data-native_password_param

當您提交密碼憑證密碼憑證處理終端,你可以指定參數名稱credential.password值。默認名稱為password 。有關詳細信息,請參閱下表:

類型必需的例子
網址可選的data-native_password_param="pwd"

數據cancel_on_tap_outside

此屬性設置如果用戶在提示之外單擊,是否取消 One Tap 請求。默認值是true 。要禁用它,將值設置為false 。有關詳細信息,請參閱下表:

類型必需的例子
布爾值可選的data-cancel_on_tap_outside="false"

數據提示_parent_id

此屬性設置容器元素的 DOM ID。如果未設置,則窗口右上角會顯示一鍵提示。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-prompt_parent_id="parent_id"

如果指定的 cookie 具有非空值,則此屬性會跳過 One Tap。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-skip_prompt_cookie="SID"

數據隨機數

此屬性是 ID 令牌用於防止重放攻擊的隨機字符串。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-nonce="biaqbm70g23"

Nonce 長度受限於您的環境支持的最大 JWT 大小,以及各個瀏覽器和服務器 HTTP 大小的限制。

數據上下文

此屬性更改 One Tap 提示中顯示的標題和消息的文本。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-context="use"

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

語境
signin “使用谷歌登錄”
signup “使用谷歌註冊”
use “與穀歌一起使用”

數據時刻_回調

該屬性是提示UI狀態通知監聽器的函數名。有關詳細信息,請參閱數據類型PromptMomentNotification 。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-moment_callback="logMomentNotification"

HTML API 不支持命名空間中的 JavaScript 函數。相反,使用沒有命名空間的全局 JavaScript 函數。例如,使用mylibCallback代替mylib.callback

如果您需要在父域及其子域中顯示 One Tap,請將父域傳遞給此屬性,以便使用單個共享狀態 cookie。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-state_cookie_domain="example.com"

數據-ux_mode

此屬性設置“使用 Google 登錄”按鈕使用的 UX 流程。默認值是popup 。此屬性對 One Tap UX 沒有影響。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-ux_mode="redirect"

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

用戶體驗模式
popup在彈出窗口中執行登錄 UX 流程。
redirect通過整頁重定向執行登錄 UX 流程。

data-allowed_pa​​rent_origin

允許嵌入中間 iframe 的來源。如果此屬性存在,One Tap 將在中間 iframe 模式下運行。有關詳細信息,請參閱下表:

類型必需的例子
字符串或字符串數組可選的data-allowed_parent_origin="https://example.com"

下表列出了支持的值類型及其說明。

值類型
string單個域 URI。 “https://example.com”
string array逗號分隔的域 URI 列表。 “https://news.example.com,https://local.example.com”

如果值data-allowed_parent_origin屬性是無效的,中間IFRAME模式的一個抽頭初始化會失敗,並停止。

還支持通配符前綴。例如, "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"將被視為無效。

data-intermediate_iframe_close_callback

當用戶通過點擊 One Tap UI 中的“X”按鈕手動關閉 One Tap 時,覆蓋默認的中間 iframe 行為。默認行為是立即從 DOM 中刪除中間 iframe。

data-intermediate_iframe_close_callback字段只需要在中間的iframe模式的效果。而且它只影響中間 iframe,而不是 One Tap iframe。在調用回調之前刪除一鍵用戶界面。

類型必需的例子
功能可選的data-intermediate_iframe_close_callback='logBeforeClose'

HTML API 不支持命名空間中的 JavaScript 函數。相反,使用沒有命名空間的全局 JavaScript 函數。例如,使用mylibCallback代替mylib.callback

具有類“g_id_signin”的元素

如果添加g_id_signin到元素的class屬性,元素呈現為在與谷歌按鈕。

您可以在同一頁面上呈現多個“使用 Google 登錄”按鈕。每個按鈕都可以有自己的視覺設置。這些設置由以下數據屬性定義。

可視化數據屬性

下表列出了可視化數據屬性及其描述:

屬性
data-type按鈕類型:圖標或標準按鈕。
data-theme按鈕主題。例如,filled_blue 或filled_black。
data-size按鈕大小。例如,小或大。
data-text按鈕文本。例如,“使用 Google 登錄”或“使用 Google 註冊”。
data-shape按鈕形狀。例如,矩形或圓形。
data-logo_alignment Google 徽標對齊方式:左對齊或居中對齊。
data-width按鈕寬度,以像素為單位。
data-locale按鈕文本以在此屬性中設置的語言呈現。

屬性類型

以下部分包含有關每個屬性類型和示例的詳細信息。

數據類型

按鈕類型。默認值是standard 。有關詳細信息,請參閱下表:

類型必需的例子
細繩是的data-type="icon"

下表列出了可用的按鈕類型及其說明:

類型
standard帶有文本或個性化信息的按鈕:
icon一個沒有文字的圖標按鈕:

數據主題

按鈕主題。默認值是outline 。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-theme="filled_blue"

下表列出了可用的主題及其說明:

主題
outline標準按鈕主題:
一個白色背景的標準按鈕一個白色背景的圖標按鈕一個白色背景的個性化按鈕
filled_blue藍色填充按鈕主題:
藍色背景的標準按鈕藍色背景的圖標按鈕藍色背景的個性化按鈕
filled_black黑色填充按鈕主題:
黑色背景的標準按鈕黑色背景的圖標按鈕黑色背景的個性化按鈕

數據大小

按鈕大小。默認值是large 。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-size="small"

下表列出了可用的按鈕大小及其說明。

尺寸
large一個大按鈕:
一個大的標準按鈕一個大圖標按鈕一個大的、個性化的按鈕
medium一個中等大小的按鈕:
中等標準按鈕中等圖標按鈕
small一個小按鈕:
一個小按鈕一個小圖標按鈕

數據文本

按鈕文本。默認值是signin_with 。有針對具有不同的圖標按鈕的文本,沒有視覺上的差異data-text屬性。唯一的例外是當為了屏幕可訪問性而讀取文本時。

有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-text="signup_with"

下表列出了可用的按鈕文本及其說明:

文本
signin_with按鈕文本為“使用 Google 登錄”:
標有“使用 Google 登錄”的標準按鈕一個沒有可見文本的圖標按鈕
signup_with按鈕文字是“Sign up with Google”:
標有“使用 Google 註冊”的標準按鈕一個沒有可見文本的圖標按鈕
continue_with按鈕文字是“Continue with Google”:
標有“繼續使用 Google”的標準按鈕一個沒有可見文本的圖標按鈕
signup_with按鈕文本是“登錄”:
標有“登錄”的標準按鈕一個沒有可見文本的圖標按鈕

數據形狀

按鈕形狀。默認值是rectangular 。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-shape="rectangular"

下表列出了可用的按鈕形狀及其說明:

形狀
rectangular矩形按鈕。如果用於icon按鈕類型,它是同square
一個矩形標準按鈕一個矩形圖標按鈕一個長方形的個性化按鈕
pill丸狀按鈕。如果用於icon按鈕式,那麼它是一樣的circle
一個藥丸狀標準按鈕一個藥丸形狀的圖標按鈕一個藥丸形狀的個性化按鈕
circle圓形按鈕。如果用於standard按鈕式,那麼它是一樣的pill
圓形標準按鈕一個圓形圖標按鈕一個圓形的個性化按鈕
square方形按鈕。如果用於standard按鈕式,那麼它是一樣的rectangular
一個方形標準按鈕一個方形圖標按鈕一個方形的個性化按鈕

data-logo_alignment

Google 徽標的對齊方式。默認值是left 。此屬性僅適用於standard按鍵式。有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-logo_alignment="center"

下表列出了可用的路線及其說明:

logo_alignment
left左對齊 Google 徽標:
左側帶有 G 標誌的標準按鈕
center居中對齊 Google 徽標:
中央帶有 G 標誌的標準按鈕

數據寬度

最小按鈕寬度,以像素為單位。可用的最大寬度為 400 像素。

有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-width=400

數據區域

按鈕文本的預設語言環境。如果未設置,則使用瀏覽器的默認區域設置或 Google 會話用戶的首選項。因此,不同的用戶可能會看到不同版本的本地化按鈕,並且可能具有不同的大小。

有關詳細信息,請參閱下表:

類型必需的例子
細繩可選的data-locale="zh_CN"

服務器端集成

服務器端的端點必須處理好以下幾個HTTP POST請求。

ID 令牌處理程序端點

ID 令牌處理程序端點處理 ID 令牌。根據相應帳戶的狀態,您可以登錄用戶並將他們定向到註冊頁面或將他們定向到帳戶鏈接頁面以獲取更多信息。

在HTTP POST請求中包含以下信息:

格式姓名描述
曲奇餅g_csrf_token隨對處理程序端點的每個請求而更改的隨機字符串。
請求參數g_csrf_token一個字符串,這是一樣的前一個cookie值, g_csrf_token .
請求參數credential Google 頒發的 ID 令牌。
請求參數select_by如何選擇憑據。

解碼時,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": "Eliza",
  "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"
}

下表列出了可能的值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 帳戶,然後按“確認”按鈕同意並共享憑據。

密碼憑證處理程序端點

密碼憑證處理程序端點處理本機憑證管理器檢索的密碼憑證。

在HTTP POST請求中包含以下信息:

格式姓名描述
曲奇餅g_csrf_token隨對處理程序端點的每個請求而更改的隨機字符串。
請求參數g_csrf_token一個字符串,這是一樣的前一個cookie值, g_csrf_token
請求參數email Google 頒發的此 ID 令牌。
請求參數password如何選擇憑據。