警告:這項資料是依據《 Google 使用者資料政策》規定提供。請詳閱並遵守相關政策。否則可能會導致專案或帳戶遭到停權。

使用 Google JavaScript API 登入

此參考資料頁面說明 Sign-In JavaScript API。您可以使用這個 API 在網頁中顯示 One Tap 提示或「使用 Google 帳戶登入」按鈕。

方法:google.accounts.id.初始化

google.accounts.id.initialize 方法會根據設定物件來初始化「使用 Google 帳戶登入」用戶端。以下的程式碼範例範例如下:

google.accounts.id.initialize(IdConfiguration)

下列程式碼範例使用 onload 函式實作 google.accounts.id.initialize 方法:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

資料類型:IdConfiguration

下表列出 IdConfiguration 資料類型的欄位與說明:

欄位
client_id 您應用程式的用戶端 ID
auto_select 啟用自動選取功能。
callback 處理 ID 憑證的 JavaScript 函式。Google One Tap 和「使用 Google 帳戶登入」按鈕 popup 使用者體驗模式會使用這項屬性。
login_uri 您的登入端點網址。「使用 Google 帳戶登入」按鈕 redirect 使用者體驗模式會使用這項屬性。
native_callback 處理密碼憑證的 JavaScript 函式。
cancel_on_tap_outside 如果使用者點選提示之外的位置,取消提示。
prompt_parent_id One Tap 提示容器元素的 DOM ID
nonce ID 憑證的隨機字串
context 「輕觸一下」提示中的標題和字詞
state_cookie_domain 如果需要在上層網域及其子網域上呼叫 One Tap,請將上層網域傳送至這個欄位,系統就會使用單一共用 Cookie。
ux_mode 「使用 Google 帳戶登入」按鈕 UX 流程
allowed_parent_origin 允許嵌入中繼 iframe 的來源。如果顯示這個欄位,「One Tap」就會在中間的 iframe 模式中執行。
intermediate_iframe_close_callback 當使用者手動關閉 One Tap 時,會覆寫預設的中繼 iframe 行為。
itp_support 在 ITP 瀏覽器中啟用升級後的 One Tap 使用者體驗。

client_id

這個欄位是應用程式的用戶端 ID,可在 Google Developers Console 中找到及建立。詳情請參閱下表:

類型 必要 範例
字串 client_id: "CLIENT_ID.apps.googleusercontent.com"

自動選取

這個欄位可決定當以前只已核准一個 Google 工作階段時,該 ID 憑證是否會自動傳回使用者沒有任何互動。預設值為 false。詳情請參閱下表:

類型 必要 範例
布林值 選用 auto_select: true

callback

這個欄位是 JavaScript 函式來處理從 One Tap 提示或彈出式視窗傳回的 ID 憑證。如果您使用 Google One Tap 或「使用 Google 帳戶登入」按鈕 popup 使用者體驗模式,就必須設定這個屬性。 詳情請參閱下表:

類型 必要 範例
function One Tap 功能和 popup 使用者體驗模式的必要項目 callback: handleResponse

login_uri

這個屬性是登入端點的 URI。如果目前的網頁是您的登入頁面,系統可能會省略該憑證。在這種情況下,系統會將憑證預設為發布到這個頁面。

當使用者使用「使用 Google 帳戶登入」按鈕及重新導向 UX 模式時,系統會將 ID 憑證憑證回應發布到您的登入端點。

詳情請參閱下表:

類型 選用 範例
網址 預設值為目前網頁的 URI 或您指定的值。
只有在已設定 ux_mode: "redirect" 時才使用。
login_uri="https://www.example.com/login"

您的登入端點必須處理含有「credential」金鑰的 POST 要求,且該主體中須包含 ID 憑證值。

以下是您登入端點的要求範例:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

native_callback

這個欄位是 JavaScript 函式的名稱,可處理從瀏覽器原生憑證管理員傳回的密碼憑證。詳情請參閱下表:

類型 必要 範例
function 選用 native_callback: handleResponse

un_on_tap_outside

這個欄位設定是否要在使用者點擊提示後,取消 One Tap 要求。預設值為 true。如果您將值設為 false,即可將其停用。詳情請參閱下表:

類型 必要 範例
布林值 選用 cancel_on_tap_outside: false

提示_上層 ID

這個屬性可設定容器元素的 DOM ID。如果未設定該提示,視窗視窗右上角會顯示「One Tap 提示」。詳情請參閱下表:

類型 必要 範例
字串 選用 prompt_parent_id: 'parent_id'

Nonce

這個欄位是 ID 權杖用來避免重複進行攻擊的隨機字串。 詳情請參閱下表:

類型 必要 範例
字串 選用 nonce: "biaqbm70g23"

無長度限制受限於您環境支援的 JWT 大小上限,以及個別瀏覽器和伺服器的 HTTP 大小限制。

context

這個欄位會變更「輕觸一次」提示訊息的標題和訊息。 詳情請參閱下表:

類型 必要 範例
字串 選用 context: "use"

下表列出了可用的背景資訊和相關說明:

背景資訊
signin 「使用 Google 帳戶登入」
signup 「立即註冊 Google」
use 「與 Google 搭配使用」

如果您需要在上層網域及其子網域中顯示 One Tap,請將上層網域傳送至這個欄位,讓系統使用單一共用狀態 Cookie。詳情請參閱下表:

類型 必要 範例
字串 選用 state_cookie_domain: "example.com"

ux_mode

您可以使用這個欄位來設定「使用 Google 帳戶登入」按鈕的使用者體驗流程。預設值為 popup。這個屬性對 OneTap UX 沒有影響。詳情請參閱下表:

類型 必要 範例
字串 選用 ux_mode: "redirect"

下表列出了可用的使用者體驗模式及其說明。

使用者體驗模式
popup 在彈出式視窗中執行登入 UX 流程。
redirect 執行完整網頁重新導向,執行登入使用者體驗流程。

允許父項來源

允許嵌入中繼 iframe 的來源。如果其中有「Tap Tap」,就會以中間 iframe 模式執行。詳情請參閱下表:

類型 必要 範例
字串或字串陣列 選用 allowed_parent_origin: "https://example.com"

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

值類型
string 單一網域 URI。 https://example.com"
string array 網域 URI 陣列。 [https://news.example.com", "https://local.example.com"]

此外,您也可以使用萬用字元前置字串。舉例來說,"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.comexample2.com 的子網域
  • 萬用字元網域必須以安全的 https:// 配置做為開頭。系統會將「"*.example.com"」視為無效。

如果 allowed_parent_origin 欄位的值無效,則中繼 iFrame 模式的 One Tap 初始化作業將會失敗並停止。

中繼_iframe_關閉_回呼

當使用者手動關閉 One Tap 的 One Tap UI 時,輕觸「#39;X'」按鈕即可覆寫預設的中間 iframe 行為。預設行為是立即從 DOM 移除中繼 iframe。

intermediate_iframe_close_callback 欄位只有在中繼 iframe 模式下才會生效。而這只會影響中間的 iframe,而不是「One Tap」的 iframe。系統會先刪除 One Tap 使用者介面,再叫用回呼。

類型 必要 範例
function 選用 intermediate_iframe_close_callback: logBeforeClose

itp_support

這個欄位可決定是否要在支援智慧防追蹤功能 (ITP) 的瀏覽器上,啟用升級版 One Tap 使用者體驗。預設值為 false。詳情請參閱下表:

類型 必要 範例
布林值 選用 itp_support: true

方法:google.accounts.id.prompt

google.accounts.id.prompt 方法會在叫用 initialize() 方法後顯示 One Tap 提示或瀏覽器原生憑證管理員。以下的程式碼範例範例如下:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

一般來說,網頁載入時就會呼叫 prompt() 方法。基於 Google 端的工作階段狀態和使用者設定,系統可能不會顯示「One Tap 提示」使用者介面。如要在不同時刻收到使用者介面狀態的通知,請傳送函式以接收 UI 狀態通知。

系統會在下列時間觸發通知:

  • 顯示時刻:系統會在呼叫 prompt() 方法之後發生。通知內含一個布林值,表示使用者介面是否顯示。
  • 已略過:當 One Tap 提示遭到自動取消、手動取消,或 Google 無法核發憑證 (例如所選工作階段登出 Google) 時,就會發生這種錯誤。

    在這類情況下,建議您繼續前往下一個識別資訊提供者 (如果有的話)。

  • 已關閉的時刻:如果 Google 成功擷取憑證,或是使用者想要停止憑證擷取流程,就會發生這種情形。例如,當使用者開始在登入對話方塊中輸入使用者名稱和密碼時,您可以呼叫 google.accounts.id.cancel() 方法來關閉 One Tap 提示並觸發關閉的時刻。

以下的程式碼範例會實作略過的時刻:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

資料類型:PromptMomentNotification

下表列出 PromptMomentNotification 資料類型的方法和說明:

方法
isDisplayMoment() 這則通知是要顯示「顯示時間」嗎?
isDisplayed() 是否顯示螢幕通知,並顯示使用者介面?
isNotDisplayed() 這則通知是否為顯示時間,卻不會顯示使用者介面?
getNotDisplayedReason()

無法顯示使用者介面的詳細原因。可能的值如下:

  • browser_not_supported
  • invalid_client
  • missing_client_id
  • opt_out_or_no_session
  • secure_http_required
  • suppressed_by_user
  • unregistered_origin
  • unknown_reason
isSkippedMoment() 這則通知是關於略過片段嗎?
getSkippedReason()

略過片段的詳細原因。可能的值如下:

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
isDismissedMoment() 這則通知是關於已關閉的時刻嗎?
getDismissedReason()

關閉的原因。可能的值如下:

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

傳回時刻類型的字串。可能的值如下:

  • display
  • skipped
  • dismissed

資料類型:CredentialResponse

叫用 callback 函式時,系統會傳送 CredentialResponse 物件做為參數。下表列出憑證回應物件中包含的欄位:

欄位
credential 這個欄位是傳回的 ID 憑證。
select_by 這個欄位可設定憑證的選取方式。

憑證

這個欄位是採用 Base64 編碼的 JSON Web Token (JWT) 字串的 ID 憑證。

解碼時,JWT 看起來會像這樣:

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": "Elisa",
  "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"
}

sub 欄位包含 Google 帳戶的全域唯一識別碼。

您可以使用 emailemail_verifiedhd 欄位來判斷 Google 是否託管及擁有電子郵件地址的權威性。如果 Google 具有權威性,目前已知的使用者是合法帳戶擁有者。

在下列情況下,Google 將視為具公信力的案例:

  • email」的後置字串為 @gmail.com,這是 Gmail 帳戶。
  • email_verified 是 true,hd 已設定,這是 G Suite 帳戶。

使用者可以註冊 Google 帳戶,而不使用 Gmail 或 G Suite。當 email 不包含 @gmail.com 後置字串,而 hd 不存在時,Google 不會產生權威性,因此建議您使用密碼或其他驗證方式來驗證使用者。email_verfied 也可能為真,因為 Google 最初在建立 Google 帳戶時驗證了使用者,但第三方電子郵件帳戶的擁有權可能已經改變。

select_by

下表列出 select_by 欄位可能的值。使用按鈕類型搭配工作階段和同意聲明狀態來設定值

  • 使用者已按下 One Tap 或「使用 Google 登入」按鈕,或使用觸控式自動登入程序

  • 已找到現有的工作階段,或者使用者選取並登入 Google 帳戶來建立新的工作階段。

  • 與使用者分享 ID 憑證憑證之前,

    • 已按下 [確認] 按鈕,表示同意分享憑證。
    • 先前已同意且使用 [選取帳戶] 來選擇 Google 帳戶

這個欄位的值設為以下其中一種類型:

說明
auto 使用先前已同意共用憑證的現有工作階段,讓使用者自動登入。
user 已有工作階段的使用者先前已同意同意聲明 會輕觸 One Tap 'Continue as' 按鈕以共用憑證。
user_1tap 已有現有工作階段的使用者會按下 One Tap 'Continue as' 按鈕,表示同意並分享憑證。僅適用於 Chrome 75 以上版本。
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 帳戶,再按下 [確認] 按鈕同意授權並分享憑證。

方法:google.accounts.id.renderButton

google.accounts.id.renderButton 方法會在您的網頁中顯示「使用 Google 帳戶登入」按鈕。

以下的程式碼範例範例如下:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

資料類型:GsiButtonConfiguration

下表列出 GsiButtonConfiguration 資料類型的欄位與說明:

屬性
type 按鈕類型:圖示或標準按鈕。
theme 按鈕主題。例如 fill_blue 或 fill_black。
size 按鈕大小。例如「小」或「大」。
text 按鈕文字。例如「使用 Google 帳戶登入」或「使用 Google 帳戶註冊」。
shape 按鈕形狀。例如:矩形或圓形。
logo_alignment Google 標誌對齊方式:靠左或置中。
width 按鈕寬度 (以像素為單位)。
locale 如果設定了,則會顯示按鈕語言。

屬性類型

以下各節將詳細說明各個屬性類型和範例。

類型

按鈕類型。預設值為 standard

詳情請參閱下表:

類型 必要 範例
字串 type: "icon"

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

類型
standard 包含文字或個人化資訊的按鈕:
icon 不含文字的圖示按鈕:

主題

按鈕主題。預設值為 outline。詳情請參閱下表:

類型 必要 範例
字串 選用 theme: "filled_blue"

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

主題
outline 標準按鈕主題:
filled_blue 藍色的按鈕主題:
filled_black 黑色的按鈕主題:

大小

按鈕大小。預設值為 large。詳情請參閱下表:

類型 必要 範例
字串 選用 size: "small"

下表列出可用的按鈕大小及相關說明:

大小
large 大型按鈕:
大型標準按鈕 大型圖示按鈕 大型的個人化按鈕
medium 中型按鈕:
中型標準按鈕中型圖示按鈕
small 小按鈕:
小型按鈕 小型圖示按鈕

傳簡訊給

按鈕文字。預設值為 signin_with。具有不同 text 屬性的圖示按鈕文字沒有視覺差異。唯一的例外是,當文字在螢幕畫面上閱讀時,就適合在螢幕畫面上閱讀。

詳情請參閱下表:

類型 必要 範例
字串 選用 text: "signup_with"

下表列出可用的按鈕文字和說明:

文字
signin_with 按鈕文字為「使用 Google 帳戶登入」:
signup_with 按鈕文字是「透過 Google 註冊」:
continue_with 按鈕文字為「透過 Google 帳戶繼續操作」:
signin 按鈕文字為「登入」:

shape

按鈕形狀。預設值為 rectangular。詳情請參閱下表:

類型 必要 範例
字串 選用 shape: "rectangular"

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

圖案
rectangular 矩形按鈕。如果用於 icon 按鈕類型,則它與 square 相同。
pill 膠囊型按鈕。如果用於 icon 按鈕類型,則它與 circle 相同。
circle 圓形的按鈕。如果用於 standard 按鈕類型,它會與 pill 相同。
square 方形按鈕。如果用於 standard 按鈕類型,它會與 rectangular 相同。

標誌對齊

Google 標誌的對齊方式。預設值為 left。這個屬性僅適用於 standard 按鈕類型。詳情請參閱下表:

類型 必要 範例
字串 選用 logo_alignment: "center"

下表列出各種對齊方式及其說明:

標誌對齊
left 靠左對齊 Google 標誌。
center 置中對齊 Google 標誌。

寬度

最小按鈕寬度 (以像素為單位)。寬度上限為 400 像素。

詳情請參閱下表:

類型 必要 範例
字串 選用 width: 400

語言代碼

按鈕文字的預設語言代碼。如未設定,系統會使用瀏覽器的預設語言代碼或 Google 工作階段使用者的偏好設定。因此,不同使用者可能會看見不同版本的本地化按鈕,而且大小可能不同。

詳情請參閱下表:

類型 必要 範例
字串 選用 locale: "zh_CN"

資料類型:憑證

叫用 native_callback 函式時,系統會傳送 Credential 物件做為參數。下表列出物件所含欄位:

欄位
id 識別使用者。
password 密碼

方法:google.accounts.id.disableAutoSelect

當使用者登出您的網站時,您必須呼叫 google.accounts.id.disableAutoSelect 方法在 Cookie 中記錄狀態。避免 UX 故障循環。此方法的程式碼片段如下:

google.accounts.id.disableAutoSelect()

下列程式碼範例使用 onSignout() 函式實作 google.accounts.id.disableAutoSelect 方法:

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

方法:google.accounts.id.storeCredential

此方法是簡易瀏覽器包裝函式,適用於瀏覽器原生憑證管理員 API 的 store() 方法。因此,這只能用來儲存密碼憑證。以下的程式碼範例範例如下:

google.accounts.id.storeCredential(Credential, callback)

下列程式碼範例使用 onSignIn() 函式實作 google.accounts.id.storeCredential 方法:

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

方法:google.accounts.id.cancel

如果您從依賴方 DOM 中移除提示,可以取消 One Tap 流程。如已選取憑證,則系統會忽略取消作業。請參閱下列程式碼範例:

google.accounts.id.cancel()

下列程式碼範例使用 onNextButtonClicked() 函式實作 google.accounts.id.cancel() 方法:

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

程式庫載入回呼:onGoogleLibraryLoad

您可以註冊 onGoogleLibraryLoad 回呼。載入「使用 Google JavaScript 登入」程式庫載入後,系統會發出通知:

window.onGoogleLibraryLoad = () => {
    ...
};

這個回呼只是 window.onload 回呼的捷徑。這種行為不會有任何差異。

下列程式碼範例會導入 onGoogleLibraryLoad 回呼:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

方法:google.accounts.id.revoke

google.accounts.id.revoke 方法會撤銷用於為指定使用者共用 ID 憑證的 OAuth 授權。請參閱下列方法的程式碼片段:google.accounts.id.revoke(hint, callback)

參數 類型 說明
hint 字串 使用者 Google 帳戶的電子郵件地址或專屬 ID。ID 是 credential 酬載的 sub 屬性。
callback function 選用的 RevocationResponse 處理常式。

下列程式碼範例示範如何將 revoke 方法與 ID 搭配使用。

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

資料類型:RevocationResponse

叫用 callback 函式時,系統會傳送 RevocationResponse 物件做為參數。下表列出撤銷回應物件所含的欄位:

欄位
successful 這個欄位是方法呼叫的傳回值。
error 這個欄位會包含詳細的錯誤回應訊息。

成功

如果撤銷方法呼叫成功或失敗,這個欄位會設為一個布林值。

錯誤

此欄位是字串值,如果撤銷方法呼叫失敗時,包含詳細錯誤訊息,則在成功時不會定義。