使用 Google HTML API 登入

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

此參考資料頁面說明瞭「使用 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_uridata-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_callbackdata-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_callbackdata-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"

如果指定的 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

如果需要在上層網域及其子網域中顯示 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.comlogin.news.example.com) 比對 example.com 及其子網域。使用萬用字元時,請注意以下幾點:

  • 模式字串不能由萬用字元和頂層網域組成。例如 https://*.comhttps://*.co.uk 無效;如上所述,"https://*.example.com" 將比對 example.com 及其子網域。您也可以使用以逗號分隔的清單,代表 2 個不同的網域。舉例來說,"https://example1.com,https://*.example2.com" 會比對 example1.comexample2.comexample2.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 帳戶登入」:
「使用 Google 帳戶登入」的標準按鈕沒有可見文字的圖示按鈕
signup_with 按鈕文字是「使用 Google 帳戶註冊」:
標示為「使用 Google 帳戶註冊」的標準按鈕沒有可見文字的圖示按鈕
continue_with 按鈕文字是「透過 Google 帳戶繼續操作」:
「繼續透過 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 標誌:
左側有 G 標誌的標準按鈕
center 置中對齊 Google 標誌:
中間有 G 標誌的標準按鈕

資料寬度

按鈕寬度下限,以像素為單位。可用的寬度上限為 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 系統選取憑證的方式。

「解碼」時,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 欄位可能的值。使用按鈕類型以及工作階段和同意聲明狀態來設定值

  • 使用者已按下 [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 系統選取憑證的方式。