此參考資料頁面說明瞭「使用 Google 帳戶登入」資料屬性 API。您可以使用這個 API,在網頁上顯示「一鍵」提示或「使用 Google 帳戶登入」按鈕。
ID 為「g_id_onload」的元素
您可以將「Sign with With Google」資料屬性放在任何可見或隱藏的元素中,例如 <div>
和 <span>
。唯一的條件是元素 ID 已設為 g_id_onload
。請勿將此 ID 用於多個元素。
資料屬性
下表列出資料屬性及其說明:
屬性 | |
---|---|
data-client_id |
應用程式用戶端 ID |
data-auto_prompt |
顯示 Google One 感應功能。 |
data-auto_select |
啟用 Google One Tap 的自動選取功能。 |
data-login_uri |
登入端點的網址 |
data-callback |
JavaScript ID 憑證處理常式函式名稱 |
data-native_login_uri |
密碼憑證處理常式端點的網址 |
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 有非空白的值,則略過 One Tap。 |
data-nonce |
ID 憑證的隨機字串 |
data-context |
「輕觸一次」提示訊息中的標題和字詞 |
data-moment_callback |
提示 UI 狀態通知事件監聽器的函式名稱 |
data-state_cookie_domain |
如果需要在上層網域及其子網域中呼叫 One Tap,請將上層網域傳送至這項屬性,以便使用單一共用 Cookie。 |
data-ux_mode |
「使用 Google 帳戶登入」按鈕的使用者體驗流程 |
data-allowed_parent_origin |
允許嵌入中繼 iframe 的來源。這項屬性 (如果有的話) 會在中間的 iframe 模式下執行。 |
data-intermediate_iframe_close_callback |
在使用者手動關閉 One Tap 時覆寫預設的中間 iframe 行為。 |
data-itp_support |
在 ITP 瀏覽器中啟用升級後的 One Tap 使用者體驗。 |
屬性類型
以下各節將詳細說明各個屬性的類型與範例。
data-client_id
這個屬性是您的應用程式用戶端 ID,可在 Google Developers Console 中找到及建立。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 可 | data-client_id="CLIENT_ID.apps.googleusercontent.com" |
data-auto_prompt
這個屬性可決定是否要顯示「輕觸一次」功能。預設值為 true
。當此值為 false
時,不會顯示 Google One 感應功能。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
布林值 | 選用 | data-auto_prompt="true" |
資料自動選取
如果只有一個 Google 工作階段核准您的應用程式,這個屬性可決定是否要在沒有使用者互動的情況下,自動傳回 ID 憑證。預設值為 false
。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
布林值 | 選用 | data-auto_select="true" |
data-login_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 函式的名稱。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 如果未設定 data-login_uri ,則為必要欄位。 |
data-callback="handleToken" |
可以使用 data-login_uri
和 data-callback
屬性之一。視下列元件和使用者體驗模式設定而定:
「使用 Google 帳戶登入」按鈕
redirect
使用者體驗模式必須使用data-login_uri
屬性,該屬性會忽略data-callback
屬性。您必須針對 Google One Tap 和 Google 登入按鈕
popup
UX 模式設定這兩個屬性的其中一個。如果同時設定兩者,data-callback
屬性的優先順序較高。
HTML API 不支援命名空間中的 JavaScript 函式。請改用沒有命名空間的全域 JavaScript 函式。例如,使用 mylibCallback
而不是 mylib.callback
。
data-native_login_uri
這個屬性是您密碼憑證處理常式端點的網址。如果您設定了 data-native_login_uri
屬性或 data-native_callback
屬性,則在沒有 Google 工作階段時,JavaScript 程式庫會改回使用原生憑證管理工具。您無法同時設定 data-native_callback
和 data-native_login_uri
屬性。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-login_uri="https://www.example.com/password_login" |
data-native_callback
這個屬性是 JavaScript 函式的名稱,用於處理瀏覽器原生憑證管理工具傳回的密碼憑證。如果您設定了 data-native_login_uri
屬性或 data-native_callback
屬性,則在沒有 Google 工作階段時,JavaScript 程式庫會改回使用原生憑證管理工具。您無法同時設定 data-native_callback
和 data-native_login_uri
。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | 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" |
data-cancel_on_tap_outside
這個屬性可設定是否要在使用者於提示以外點擊時,取消 One Tap 要求。預設值為 true
。如要停用此功能,請將值設為 false
。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
布林值 | 選用 | data-cancel_on_tap_outside="false" |
data-prompt_parent_id
這個屬性可設定容器元素的 DOM ID。如未設定,系統會在視窗右上角顯示「一觸」提示。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-prompt_parent_id="parent_id" |
data-skip_prompt_cookie
如果指定的 Cookie 有非空白的值,這個屬性會略過 One Tap。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-skip_prompt_cookie="SID" |
無數據
這項屬性是 ID 憑證使用的隨機字串,可防止重播攻擊。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-nonce="biaqbm70g23" |
Nonce 長度限制是您環境支援的 JWT 大小上限,以及個別瀏覽器和伺服器的 HTTP 大小限制。
資料情境
這個屬性會變更 One Tap 提示中顯示的標題和訊息。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-context="use" |
下表列出了背景資訊與相關說明:
背景資訊 | |
---|---|
signin |
「使用 Google 帳戶登入」 |
signup |
「使用 Google 帳戶註冊」 |
use |
「與 Google 搭配使用」 |
data-moment_callback
這個屬性是提示使用者介面狀態通知事件監聽器的函式名稱。詳情請參閱 PromptMomentNotification
資料類型。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-moment_callback="logMomentNotification" |
HTML API 不支援命名空間中的 JavaScript 函式。請改用沒有命名空間的全域 JavaScript 函式。例如,使用 mylibCallback
而不是 mylib.callback
。
資料狀態 Cookie 網域
如果需要在上層網域及其子網域中顯示 One Tap,請將上層網域傳送至這項屬性,以便使用單一共用狀態 Cookie。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-state_cookie_domain="example.com" |
資料-ux_mode
這個屬性可設定「使用 Google 帳戶登入」按鈕所使用的使用者體驗流程。預設值為 popup
。這項屬性不會影響 One Tap 使用者體驗。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-ux_mode="redirect" |
下表列出現有的使用者體驗模式及其說明。
使用者體驗模式 | |
---|---|
popup |
在彈出式視窗中執行登入流程流程。 |
redirect |
透過整頁重新導向,執行登入使用者體驗流程。 |
data-allowed_parent_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 模式的 One Tap 初始化就會失敗並停止。
系統也支援萬用字元的前置字串。舉例來說,"https://*.example.com"
會在所有層級 (例如 news.example.com
、login.news.example.com
) 比對 example.com
及其子網域。使用萬用字元時,請注意以下幾點:
- 模式字串不能由萬用字元和頂層網域組成。例如
https://*.com
和https://*.co.uk
無效;如上所述,"https://*.example.com"
將比對example.com
及其子網域。您也可以使用以逗號分隔的清單,代表 2 個不同的網域。舉例來說,"https://example1.com,https://*.example2.com"
會比對example1.com
、example2.com
和example2.com
的子網域 - 萬用字元網域的開頭必須是安全的 https:// 配置。系統會將
"*.example.com"
視為無效。
data-middle_iframe_close_callback
使用者輕觸 One Tap 使用者介面中的「X」按鈕來手動關閉 One Tap 時,將覆寫預設的中繼 iframe 行為。預設行為是立即從 DOM 移除中繼 iframe。
data-intermediate_iframe_close_callback
欄位只會在中繼 iframe 模式下生效。而只會影響中間的 iframe
(而非一鍵 iframe)系統會在叫用回呼前移除 One Tap 使用者介面。
類型 | 必填 | 範例 |
---|---|---|
函式 | 選用 | data-intermediate_iframe_close_callback="logBeforeClose" |
HTML API 不支援命名空間中的 JavaScript 函式。請改用沒有命名空間的全域 JavaScript 函式。例如,使用 mylibCallback
而不是 mylib.callback
。
data-itp_support
這個欄位可決定是否要在支援智慧防追蹤 (ITP) 的瀏覽器上,啟用升級版 One Tap 使用者體驗。預設值為 false
。詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
布林值 | 選用 | data-itp_support="true" |
含有「g_id_signin」類別的元素
如果在元素的 class
屬性中加入 g_id_signin
,該元素會顯示為「使用 Google 帳戶登入」按鈕。
您可以在同一個頁面上顯示多個「使用 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 |
按鈕文字是以此屬性中設定的語言顯示。 |
data-click_listener |
設定這個選項之後,系統會在使用者點選「使用 Google 帳戶登入」按鈕時呼叫這個函式。 |
屬性類型
以下各節將詳細說明各個屬性的類型與範例。
資料類型
按鈕類型。預設值為 standard
。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 可 | data-type="icon" |
下表列出可使用的按鈕類型及其說明:
類型 | |
---|---|
standard |
包含文字或個人化資訊的按鈕:
![]() ![]() |
icon |
不含文字的圖示按鈕:![]() |
資料主題
按鈕主題。預設值為 outline
。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-theme="filled_blue" |
下表列出了可用的主題及相關說明:
主題 | |
---|---|
outline |
標準按鈕主題:
![]() ![]() ![]() |
filled_blue |
藍色的按鈕主題:
![]() ![]() ![]() |
filled_black |
黑色的按鈕主題:
![]() ![]() ![]() |
資料大小
按鈕大小。預設值為 large
。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-size="small" |
下表列出可使用的按鈕大小及其說明。
大小 | |
---|---|
large |
大型按鈕:
![]() ![]() ![]() |
medium |
中型按鈕:
![]() ![]() |
small |
小按鈕:
![]() ![]() |
資料-文字
按鈕文字。預設值為 signin_with
。具有不同 data-text
屬性的圖示按鈕文字沒有視覺差異。唯一的例外是讀取文字,確保螢幕無障礙功能。
詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-text="signup_with" |
下表列出可使用的按鈕文字和說明:
文字 | |
---|---|
signin_with |
按鈕文字為「使用 Google 帳戶登入」:![]() ![]() |
signup_with |
按鈕文字是「使用 Google 帳戶註冊」:![]() ![]() |
continue_with |
按鈕文字是「透過 Google 帳戶繼續操作」:![]() ![]() |
signin |
按鈕文字為「登入」:![]() ![]() |
資料形狀
按鈕形狀。預設值為 rectangular
。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-shape="rectangular" |
下表列出可使用的按鈕形狀和說明:
形狀 | |
---|---|
rectangular |
矩形按鈕。如果用於 icon 按鈕類型,則會與 square 相同。![]() ![]() ![]() |
pill |
膠囊形按鈕。如果用於 icon 按鈕類型,則會與 circle 相同。![]() ![]() ![]() |
circle |
圓形的按鈕。如果用於 standard 按鈕類型,則會與 pill 相同。![]() ![]() ![]() |
square |
方形按鈕。如果用於 standard 按鈕類型,則會與 rectangular 相同。![]() ![]() ![]() |
data-logo_alignment
Google 標誌的對齊方式預設值為 left
。這個屬性僅適用於 standard
按鈕類型。詳情請參閱下表:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-logo_alignment="center" |
下表列出了可用對齊方式和相關說明:
logo_alignment | |
---|---|
left |
靠左對齊 Google 標誌:
![]() |
center |
置中對齊 Google 標誌:![]() |
資料寬度
按鈕寬度下限,以像素為單位。可用的寬度上限為 400 像素。
詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-width=400 |
資料語言代碼
按鈕文字的預設語言代碼。如未設定,則會使用瀏覽器的預設語言代碼或 Google 工作階段使用者的偏好設定。因此,不同使用者可能會看見不同版本的本地化按鈕,且可能使用不同的大小。
詳情請見下表內容:
類型 | 必填 | 範例 |
---|---|---|
string | 選用 | data-locale="zh_CN" |
click_listener
您可以使用 click_listener
屬性定義當使用者點選「使用 Google 帳戶登入」按鈕時,要呼叫的 JavaScript 函式。
google.accounts.id.renderButton(document.getElementById("signinDiv"), { theme: 'outline', size: 'large', click_listener: onClickHandler }); function onClickHandler(){ console.log("Sign in with Google button clicked...") }
在上述範例中,當您點選 [使用 Google 帳戶登入] 按鈕時,系統會在控制台登入「使用 Google 帳戶登入」按鈕。
伺服器端整合
您的伺服器端端點必須處理下列 HTTP POST
要求。
ID 憑證處理常式端點
ID 憑證處理常式端點會處理 ID 憑證。您可以根據對應的帳戶狀態登入使用者,並將使用者導向註冊頁面,或將他們導向帳戶連結頁面以取得詳細資訊。
HTTP POST
要求包含下列資訊:
格式 | 名稱 | 說明 |
---|---|---|
Cookie | g_csrf_token |
一個隨機字串,會隨著每次對處理常式端點變更的要求而變更。 |
要求參數 | g_csrf_token |
與前一個 Cookie 值「g_csrf_token 」相同的字串 |
要求參數 | credential |
Google 核發的 ID 權杖。 |
要求參數 | select_by |
系統選取憑證的方式。 |
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
欄位可能的值。使用按鈕類型以及工作階段和同意聲明狀態來設定值
使用者已按下 [One Tap] 或 [Sign In With Google] 按鈕,或使用非感應式自動登入程序。
找到現有的工作階段,或使用者選取並登入 Google 帳戶以建立新的工作階段。
與應用程式共用 ID 憑證憑證之前,使用者
- 按下 [確認] 按鈕同意授權分享憑證,或
- 先前已取得同意聲明,並使用「選取帳戶」 選擇 Google 帳戶
這個欄位的值設為以下其中一種類型:
值 | 說明 |
---|---|
auto |
針對先前已同意分享憑證的現有工作階段,自動登入使用者。 |
user |
現有工作階段中,若先前已獲得使用者同意,請按下 [輕觸操作] 按鈕分享憑證。 |
user_1tap |
目前已有工作階段的使用者按下 [輕觸操作] 按鈕,表示同意並分享憑證。僅適用於 Chrome 75 以上版本。 |
user_2tap |
沒有現有工作階段的使用者按下 [輕觸操作] 按鈕選取帳戶,然後按下彈出式視窗中的 [確認] 按鈕,表示同意並分享憑證。適用於非 Chromium 瀏覽器。 |
btn |
使用者已有工作階段,先前同意的使用者按下 [使用 Google 帳戶登入] 按鈕,並從「選擇帳戶」中選取一個 Google 帳戶來共用憑證。 |
btn_confirm |
已有現有工作階段的使用者已按下 [使用 Google 帳戶登入] 按鈕,並按下 [確認] 按鈕同意授權並分享憑證。 |
btn_add_session |
沒有已取得同意聲明的現有使用者,按下「使用 Google 帳戶登入」按鈕,即可選取 Google 帳戶並分享憑證。 |
btn_confirm_add_session |
沒有現有工作階段的使用者先按下「使用 Google 帳戶登入」按鈕選取 Google 帳戶,再按下 [確認] 按鈕同意並分享憑證。 |
密碼憑證處理常式端點
密碼憑證處理常式端點會處理原生憑證管理員擷取的密碼憑證。
HTTP POST
要求包含下列資訊:
格式 | 名稱 | 說明 |
---|---|---|
Cookie | g_csrf_token |
一個隨機字串,會隨著每次對處理常式端點變更的要求而變更。 |
要求參數 | g_csrf_token |
與前一個 Cookie 值 g_csrf_token 相同的字串。 |
要求參數 | email |
Google 核發的這組 ID 符記。 |
要求參數 | password |
系統選取憑證的方式。 |