使用 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_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	系統選取憑證的方式。

「解碼」時，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	系統選取憑證的方式。