警告:此數據是根據Google用戶數據政策提供的。請查看並遵守政策。否則可能會導致項目或帳戶被暫停。
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

使用Google HTML API參考登錄

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

標識為“ g_id_onload”的元素

您可以將“使用Google登錄”數據屬性放在任何可見或不可見的元素中,例如<div><span> 。唯一的要求是將元素ID設置為g_id_onload 。請勿將此ID放在多個元素上。

資料屬性

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

屬性
data-client_id您的應用程序的客戶端ID
data-auto_prompt顯示Google一鍵式。
data-auto_select在Google一鍵式啟用自動選擇。
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一鍵式提示容器元素的DOM ID
data-skip_prompt_cookie如果指定的cookie具有非空值,則跳過一鍵。
data-nonce ID令牌的隨機字符串
data-context一鍵式提示中的標題和單詞
data-moment_callback提示UI狀態通知偵聽器的函數名稱
data-state_cookie_domain如果您需要在父域及其子域中調用“一鍵式”,請將父域傳遞給此屬性,以便使用單個共享cookie。
data-ux_mode使用Google登錄按鈕UX流
data-allowed_parent_origin允許嵌入中間iframe的原點。如果出現此屬性,則一鍵式將在中間iframe模式下運行。
data-intermediate_iframe_close_callback當用戶手動關閉“一鍵式”時,將覆蓋默認的中間iframe行為。

屬性類型

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

data-client_id

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

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

數據自動提示

此屬性確定是否顯示“單擊”。默認值為true 。如果該值為false則不會顯示Google One Tap。有關更多信息,請參見下表:

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

數據自動選擇

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

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

data-login_uri

此屬性是您的登錄端點的URL。有關更多信息,請參見下表:

類型必需的例子
網址redirect UX模式必需data-login_uri="https://example.com/login"

數據回叫

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

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

可以使用data-login_uridata-callback屬性之一。它取決於以下組件和UX模式配置:

  • 使用Google登錄按鈕redirect UX模式需要data-login_uri屬性,該模式將忽略data-callback屬性。

  • 必須為Google一鍵式設置和Google登錄按鈕popup UX模式設置這兩個屬性之一。如果兩者都設置,則data-callback屬性具有更高的優先級。

data-native_login_uri

此屬性是您的密碼憑證處理程序終結點的URL。如果您設置data-native_login_uri屬性或data-native_callback屬性,則在沒有Google會話時,JavaScript庫將退回到本機憑證管理器。不允許同時設置data-native_callbackdata-native_login_uri屬性。有關更多信息,請參見下表:

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

data-native_callback

此屬性是處理從瀏覽器的本機憑證管理器返回的密碼憑證的JavaScript函數的名稱。如果您設置data-native_login_uri屬性或data-native_callback屬性,則在沒有Google會話時,JavaScript庫將退回到本機憑證管理器。不允許同時設置data-native_callbackdata-native_login_uri 。有關更多信息,請參見下表:

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

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"

data-cancel_on_tap_outside

此屬性設置如果用戶在提示之外單擊,則是否取消“一鍵式”請求。默認值為true 。要禁用它,請將值設置為false 。有關更多信息,請參見下表:

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

data-prompt_parent_id

此屬性設置容器元素的DOM ID。如果未設置,則在窗口的右上角顯示“一鍵式”提示。有關更多信息,請參見下表:

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

如果指定的cookie具有非空值,則此屬性跳過“一鍵式”。有關更多信息,請參見下表:

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

數據現今

此屬性是ID令牌用來防止重放攻擊的隨機字符串。有關更多信息,請參見下表:

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

數據上下文

此屬性更改“一鍵式”提示中顯示的標題和消息的文本。有關更多信息,請參見下表:

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

下表列出了可用的上下文及其描述:

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

data-moment_callback

此屬性是提示UI狀態通知偵聽器的功能名稱。有關更多信息,請參考數據類型PromptMomentNotification 。有關更多信息,請參見下表:

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

如果需要在父域及其子域中顯示“單擊”,請將父域傳遞給此屬性,以便使用單個共享狀態cookie。有關更多信息,請參見下表:

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

數據輔助模式

此屬性設置“使用Google登錄”按鈕使用的UX流。默認值為popup 。此屬性對“一鍵式UX”沒有影響。有關更多信息,請參見下表:

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

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

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

data-allowed_pa​​rent_origin

允許嵌入中間iframe的原點。如果出現此屬性,則一鍵式將在中間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

當用戶通過單擊“一鍵式”用戶界面中的“ X”按鈕手動關閉“一鍵式”時,將覆蓋默認的中間iframe行為。默認行為是立即從DOM中刪除中間iframe。

data-intermediate_iframe_close_callback字段僅在中間iframe模式下有效。而且它僅對中間iframe產生影響,而對One Tap iframe則沒有影響。在調用回調之前,將刪除“一鍵式” UI。

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

類為“ g_id_signin”的元素

如果將g_id_signin添加到元素的class屬性,則該元素將呈現為“使用Google登錄”按鈕。

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

視覺數據屬性

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

屬性
data-type按鈕類型:圖標或標準按鈕。
data-theme按鈕主題。例如,白色或藍色。
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按鈕文字為“使用Google註冊”:
標有“通過Google註冊”的標準按鈕沒有可見文字的圖標按鈕
continue_with按鈕文字為“繼續使用Google”:
標有“與Google繼續”的標準按鈕沒有可見文字的圖標按鈕
signup_with按鈕文字為“登錄”:
標有“登錄”的標準按鈕沒有可見文字的圖標按鈕

數據形狀

按鈕形狀。默認值為rectangular 。有關更多信息,請參見下表:

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

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

形狀
rectangular矩形按鈕。如果用於icon按鈕類型,則與square相同。
矩形標準按鈕矩形圖標按鈕矩形個性化按鈕
pill藥丸狀的按鈕。如果用於icon按鈕類型,則與circle相同。
藥丸狀的標準鈕扣藥丸形的圖標按鈕藥丸狀的個性化按鈕
circle圓形按鈕。如果用於standard按鈕類型,則與pill相同。
圓形標準按鈕圓形圖標按鈕圓形個性化按鈕
square方形按鈕。如果用於standard按鈕類型,則與rectangular相同。
方形標準按鈕方形圖標按鈕方形個性化按鈕

數據徽標對齊

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 .相同的字符串g_csrf_token .
請求參數credential Google發行的ID令牌。
請求參數select_by憑證的選擇方式。

下表列出了select_by字段的可能值。與會話和同意狀態一起使用的按鈕類型用於設置值,

  • 用戶按下“一鍵式”或“使用Google登錄”按鈕,或使用非接觸式自動登錄過程。

  • 找到現有會話,或選擇用戶並登錄到Google帳戶以建立新會話。

  • 在與您的應用共享ID令牌憑證之前,用戶要么

    • 按“確認”按鈕以同意他們共享憑據,或者
    • 先前已同意並使用“選擇帳戶”來選擇一個Google帳戶。

該字段的值設置為以下類型之一,

價值描述
auto具有現有會話的用戶的自動登錄,該用戶先前已同意共享憑據。
user擁有現有會話且之前已獲得同意的用戶按下了“輕按”作為共享憑據的“繼續為”按鈕。
user_1tap具有現有會話的用戶按下“輕按”作為“繼續”按鈕以授予同意並共享憑據。僅適用於Chrome v75及更高版本。
user_2tap沒有現有會話的用戶按下“點擊繼續”按鈕以選擇一個帳戶,然後在彈出窗口中按下“確認”按鈕以授予同意並共享憑據。適用於非基於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憑證的選擇方式。