Chrome 將於 2024 年第 1 季淘汰第三方 Cookie。請按照遷移指南查看潛在變更，避免使用者登入網站時受到負面影響。

本頁面由 Cloud Translation API 翻譯而成。

整合注意事項

這份逐步指南可協助您判斷所有的重大整合問題。

抽象化「使用 Google 帳戶登入」功能

以下是使用者在網站上登入 / 註冊的一般步驟。

使用者會登入 Google 網站。

瀏覽器可透過「使用 Google 帳戶登入」功能順利運作。只有在使用者於載入網頁前登入 Google 時，才會觸發 One Tap 和自動登入。針對「使用 Google 帳戶登入」按鈕流程，您可以選擇是否要執行此步驟，因為使用者按下按鈕時，系統會提示使用者登入 Google。

重點： 基於安全考量，您無法在 iframe 中新增 Google 工作階段。
使用者瀏覽網頁時，其中內嵌了 One Tap、自動登入或「使用 Google 帳戶登入」按鈕。

重點： 您可以使用程式碼產生器輕鬆產生程式碼，將 One Tap、自動登入和「使用 Google 帳戶登入」按鈕嵌入網頁。
使用者會與 One Tap、「使用 Google 帳戶登入」按鈕和後續使用者體驗流程互動，例如：
- 如要繼續操作，請選取執行中的 Google 工作階段。
- 您必須先取得使用者的同意，才能將設定檔資訊提供給您的網站 (如果尚未同意)。
重點：如果使用者之前只授予一個 Google 執行中的工作階段，且您的網站啟用了這項功能，系統就會執行自動登入。
注意：只有 One Tap 使用者體驗能執行自動登入，使用者無法使用「使用 Google 帳戶登入」按鈕。

如果瀏覽器中只有一個執行中的 Google 工作階段，
- One Tap 會自動選取唯一的工作階段，因此略過帳戶選擇工具頁面。
- 「Sign in with Google」按鈕會留在帳戶選擇工具頁面上，可讓使用者在需要時新增 Google 工作階段。
如果所選 Google 帳戶從未用於您的網站，或是權限遭到撤銷，系統會顯示同意頁面。

要求獲得核准後，Google 會記錄決定，因此下次略過同意聲明頁面時即可。
包含使用者名稱、電子郵件地址和個人資料相片的 JSON Web Token (也稱為 ID 權杖) 憑證，會透過 JavaScript 回呼處理常式或提交至後端服務的貼文來共用。

要在用戶端將 ID 權杖傳回至 JavaScript 回呼處理常式，而不是在 JavaScript 程式碼中解碼該憑證，而是讓您以自己的方式將其提交至伺服器。其中一個好例子是使用 XmlHttpRequest ，避免網頁提交後造成的網頁重新載入。

重點： 如要在不重新載入網頁的情況下進行驗證，常見的做法是透過 JavaScript 回呼處理常式接收 JWT 憑證，然後透過 XmlHttpRequest 將憑證提交給您的伺服器。
在伺服器端，Google 核發的 JWT 憑證會經過驗證，並使用該憑證在您的網站中建立新帳戶或建立經過驗證的工作階段。

您可在自家網站上管理使用者登入狀態。

使用者的 Google 帳戶登入狀態，應用程式彼此獨立，但如果您知道使用者已成功通過驗證並登入 Google 帳戶，則在登入期間本身不會出現應用程式。使用者可能會保持登入狀態、登出或改用其他 Google 帳戶，同時繼續在您的網站上維持有效的登入工作階段。

總結來說，例如以密碼為基礎的登入方式，「使用 Google 帳戶登入」功能可讓您以另一種方式在網路上驗證使用者。驗證完畢後，「使用 Google 帳戶登入」功能就不會為網站的工作階段管理提供任何功能。

存取 Google API 和服務

如上所述，整合了 Authentication API，若網站需要代表已驗證使用者存取 Google API 和服務，您可能還需要整合 Authorization API。驗證可為網站提供 ID 權杖以驗證使用者，但授權會為網站提供 (個別) 存取權杖和使用 Google API 和服務的權限。詳情請參閱授權網頁。

將驗證和授權的使用者體驗區隔開來

如果您的網站需要同時呼叫驗證和授權 API，您必須在不同的時刻分別呼叫這些 API。請參閱區分驗證與授權時刻一節。

如果您的網站曾同時要求驗證和授權權杖，則使用 Google Identity Services JavaScript 程式庫時，您必須調整使用者體驗，將驗證時間與授權時間分開。

在驗證程序中，您的網站可以與 One Tap、自動登入或「使用 Google 帳戶登入」按鈕整合，讓使用者可以登入或註冊您的網站。
在授權期間，您的網站可以叫用授權 API，以便取得存取 Google API 或服務的權限和權杖。

為順利轉換使用者體驗並降低複雜度，常見的做法是將程序分為兩個獨立步驟。

重構使用者體驗，將驗證和授權時刻區隔開來。
請遷移至 Google Identity Services JavaScript 程式庫。

重點： 我們將著重於驗證階段的 API 和功能。如要瞭解授權 API 和功能，請參閱授權 API 文件。

HTML API 與 JavaScript API

您可以使用 HTML API 或 JavaScript API，將 One Tap、自動登入或「使用 Google 帳戶登入」按鈕整合至網頁中。

使用 HTML API，您有更多內建功能。比如

載入網頁時轉譯 One Tap 或「使用 Google 帳戶登入」按鈕。
在「One Tap」、「自動登入」或「按鈕彈出式視窗/重新導向」的使用者體驗之後，將傳回的憑證提交給伺服器端端點，由 data-login_uri 屬性指定。
透過 double-submit-cookie 防止 CSRF 攻擊。
請使用程式碼產生器產生 HTML 程式碼，然後直接複製到 HTML 網頁中。

使用 HTML API 時，您也可以編寫一些 JavaScript 來自訂行為。

您可以編寫自己的回呼處理常式，然後將函式名稱設為 data-callback 屬性。使用 XmlHttpRequest 將傳回的憑證提交給您的伺服器，可以避免預設提交後造成網頁重新載入。

重點提示： 如要在不重新載入網頁的情況下進行驗證，常見的做法是透過 JavaScript 回呼處理常式接收 JWT 憑證，然後透過 XmlHttpRequest 提交憑證。

使用 JavaScript API 時，您有更多彈性，如下所示。

稍後正在轉譯 One Tap 和「使用 Google 帳戶登入」按鈕。例如，使用者從選單中選取「Login」後。
多次呼叫 API。舉例來說，每次轉譯登入對話方塊時，都必須轉譯「使用 Google 帳戶登入」按鈕。
以動態方式產生 HTML 網頁，使網頁難以嵌入 API 呼叫程式碼。
您稍後會載入 Google Identity Services JavaScript 程式庫。

HTML API 程式碼只能在 onload 事件或 Google Identity Services JavaScript 程式庫 onload 事件上叫用一次 (兩者取其先)。如果 HTML API 行為不符合預期，您應使用 JavaScript API。

請勿在相同網頁中使用 HTML API 搭配 JavaScript API 來初始化網頁，也不要針對 One Tap 和按鈕轉譯。檢查 HTML 和 JavaScript 程式碼，找出兩者重疊的位置。請注意：

如果 HTML 程式碼有 <div id='g_id_onload' ... ><id> 或 <div class='g_id_signin' ...></div> 中的一或多個元素，您必須使用 HTML API。
如果在 JavaScript 程式碼中叫用 initialize()、prompt() 或 render() 中的一或多個方法，無論這些方法是內嵌或從分隔的 JavaScript 檔案載入，您正在使用 JavaScript API。

下列 JavaScript API 可能與初始化或 One Tap 和按鈕轉譯作業分開使用；它們沒有對應的 HTML API：

「使用 Google 帳戶登入」按鈕注意事項

彈出式視窗與重新導向

OAuth 2.0 規格會將 HTTP 重新導向納入考量，但缺少轉譯彈出式對話方塊的相關指引。彈出式使用者體驗 (尤其是電腦版網站) 可能會為使用者提供更優質的使用者體驗。這是因為使用者不會從第三方網頁重新導向，而類似對話方塊的彈出式視窗會提供權限許可的體驗。

使用彈出式視窗使用者體驗時，識別資訊提供者必須在用戶端跨來源通訊管道上進行建構，從顯示識別資訊提供者同意聲明頁面的彈出式視窗，將 OAuth 回應傳送至顯示第三方頁面的主要視窗。一般來說，兩端都需要 JavaScript 程式碼，才能跨視窗傳送及接收 OAuth 回應。

彈出式視窗和重新導向的使用者體驗都是「使用 Google 帳戶登入」按鈕。根據預設，系統將使用彈出式視窗的使用者體驗。您可以設定 data-ux_mode 屬性來變更使用者體驗。

「使用 Google 帳戶登入」按鈕重新導向流程和 OAuth 重新導向流程稍有不同。

「使用 Google 帳戶登入」按鈕重新導向流程一律會使用 POST 方法將憑證提交至您的網路伺服器，而 OAuth 重新導向則通常會使用 GET 方法。
「使用 Google 帳戶登入」按鈕重新導向流程所提交的參數與 OAuth 重新導向流程不同。

對於使用 HTML API 的開發人員，無論使用的使用者體驗為何，系統一律會使用 POST 方法和相同的參數將憑證提交至 data-login_uri。這樣一來，您不必變更其他程式碼，就能切換使用者體驗模式。如要進行重新導向使用者體驗，必須在 Google API 控制台中，將 data-login_uri 新增至用戶端的已授權的重新導向 URI。

自訂按鈕

不支援使用自己的按鈕。沒有任何 API 可透過程式輔助方式啟動按鈕流程。

如要啟用「使用 Google 帳戶登入」按鈕流程，您只需要在您的網頁上呈現一或多個「使用 Google 帳戶登入」按鈕即可。當使用者點選這些按鈕時，按鈕流程會以公開透明的方式啟動並進行處理。

按鈕轉譯 API 可讓您自訂「使用 Google 帳戶登入」按鈕的外觀和風格。建議您使用程式碼產生器來互動式設計按鈕。即使您使用 JavaScript API，還是可以先產生 HTML 程式碼，然後將程式碼複製到 JavaScript API 中的對應欄位。

目前沒有 API 可讓網站控管是否應使用個人化資訊來轉譯按鈕。如果符合所有條件，就會顯示個人化按鈕。詳情請參閱瞭解個人化按鈕。

您可以在同一個網頁中加入多個按鈕。程式碼產生器每次只能建立一個按鈕。您可以執行多次，並將產生的 <div class='g_id_signin' ...></div> 程式碼複製到網頁中。

按鈕顯示最佳做法

基於隱私因素，個人化按鈕會顯示在 accounts.google.com 網域的 iframe 中。如果網路速度緩慢，載入 iframe 可能會耗費大量時間。為減少此延遲問題，按鈕會以 2 個步驟顯示，如下所示：

內嵌按鈕版本會在網站的 DOM 樹狀結構中轉譯。這只是文字按鈕，無法使用個人化資訊目的是讓使用者能盡快看到按鈕。
iframe 要求會傳送至 Google 以載入按鈕 iframe，其中可能包含個人化資訊。載入按鈕 iframe 後，系統就會移除內嵌版本按鈕。

以下列出一些最佳做法，可以縮短顯示「使用 Google 帳戶登入」按鈕流程按鈕的延遲時間。

盡早載入 Google Identity Services JavaScript 程式庫。建議先載入 JavaScript 程式庫，再載入其他大型程式庫，特別是在行動版網站上。
如果只有在使用者從選單中選取「Login」後，系統才會顯示「使用 Google 帳戶登入」按鈕。您可以先在隱藏的元素中顯示「使用 Google 帳戶登入」按鈕，然後在使用者從選單中選取「Login」後顯示。

重點： 請盡早載入 Google Identity Services JavaScript 程式庫，以盡可能縮短顯示「使用 Google 帳戶登入」按鈕時的延遲時間。

One Tap 相關注意事項

自動登入

可取消的自動登入具備下列優點，

儲存一個使用者動作可以提高登入率。
與之前提供的無訊息登入 Google 登入 JavaScript 程式庫不同，使用者會自動在自動登入時看到一些 UI，瞭解登入網站的原因和方式。使用者也可以視需要取消訂閱。
該功能會自動選取使用者之前使用的帳戶，避免使用者在網站上建立重複帳戶。

是否要啟用自動登入功能取決於網站的使用者體驗和業務需求。特別是，如果大多數從網站登出是因工作階段逾時 (而非使用者明確選擇) 所導致，自動登入是為使用者提供復原工作階段狀態的好方法。

One Tap 使用者介面顯示時機

使用 HTML API 後，載入網頁時一律顯示「One Tap」。使用 JavaScript

API 時，您可以控制 One Tap 使用者介面顯示的時間。請注意，基於以下幾個原因，單點使用者介面不一定會在叫用 API 後顯示。

瀏覽器中沒有執行中的 Google 工作階段。
所有進行中的 Google 工作階段都會退出。
等待期正在進行中。

請勿嘗試在按鈕點擊事件上只顯示 One Tap 使用者介面。One Tap 使用者介面可能基於上述原因而未顯示，且使用者可能會因使用者操作後未顯示任何資訊，導致使用者體驗無法正常運作。在按鈕點擊事件上：

建議

顯示使用密碼登入和「使用 Google 帳戶登入」按鈕的登入對話方塊，並同時呼叫 One Tap API。如此可確保使用者一律能以某種方式登入您的網站。

不建議採用

如果只提供 One Tap，如果使用者未顯示「One Tap」，則登入體驗可能會中斷。
如果 One Tap 未顯示，請使用 UI 狀態回呼顯示另一個 UI。我們不建議這麼做，因為在日後推出的版本中，UI 狀態回呼可能不適用於聯合憑證管理。

透過 ITP 瀏覽器使用 One Tap

由於智慧追蹤預防機制 (ITP)，一般 One Tap UX 不適用於 iOS、Safari 和 Firefox 等 ITP 瀏覽器。這些瀏覽器會提供以歡迎頁面開頭的其他使用者體驗。

如有需要，可以停用 ITP 瀏覽器的 One Tap UX。詳情請參閱「ITP 瀏覽器的 One Tap 支援」。

您無法在非 ITP 瀏覽器上啟用此使用者體驗，例如在 Android/macOS/Linux 和 Edge 上的 Chrome。

如果使用者按一下離開，則取消提示

根據預設，如果使用者點選提示以外的內容，「One Tap 提示」會自動關閉。如有需要，您可以變更這個行為。

由於螢幕尺寸夠大，建議您在電腦版網站保持 One Tap 提示開啟。

變更 One Tap 使用者體驗的位置

你可以在電腦版網站上變更 One Tap 提示的位置。不過，由於在日後推出的版本中聯合憑證管理不支援這項功能，因此我們不建議使用這項功能。

變更登入內容

這時，網站使用者體驗應能提升。根據預設，系統會在登入內容中使用 One Tap UI。UI 的語言包含特定字詞，例如「登入」。您可以變更結構定義屬性，建立不同的字詞組合。您可以選取最符合使用者體驗流程的 One Tap 標頭。

內容脈絡
`signin`	「使用 Google 帳戶登入」
`signup`	「使用 Google 帳戶註冊」
`use`	「透過 Google 使用」

監聽 One Tap 使用者介面狀態

為了完美整合至大型使用者體驗流程，One Tap 可在 UI 狀態變更時通知您。不過，日後的聯合憑證管理版本不支援這項功能。

跨子網域使用 One Tap

根據預設，系統會針對各個來源追蹤 One Tap 等待期和其他狀態。如果您的網站在多個子網域中顯示 One Tap，您必須在 API 程式碼中指明。

在靜態 HTML 頁面中使用 One Tap

GIS 程式庫預設會假設網頁是以動態方式產生。HTTP 伺服器在產生 HTML 程式碼時，會檢查使用者登入狀態。

如果沒有使用者登入，結果網頁中就應納入 One Tap HTML 程式碼，以便觸發 One Tap 讓使用者登入您的網站。
如果使用者已經登入，產生的頁面就不應包含 One Tap HTML 程式碼。

在這種情況下，您的網路伺服器必須負責新增或移除 One Tap HTML API 程式碼。

One Tap HTML API 程式碼可透過另一種方式運作，這是專為代管大量靜態 HTML 內容的網站所設計。您可以隨時在靜態 HTML 網頁中加入 One Tap HTML API 程式碼，並指定網站中使用的工作階段 Cookie 名稱。

如果工作階段 Cookie 不存在，系統會觸發 One Tap 流程。
如果工作階段 Cookie 存在，系統就會略過 One Tap 流程。

在這種情況下，是否觸發 One Tap 流程是由工作階段 Cookie 狀態控制，而不是網頁上是否有 One Tap HTML API 程式碼。

伺服器端整合

完成 One Tap 自動登入或「使用 Google 帳戶登入」按鈕的使用者體驗流程後，系統會核發 ID 權杖並提供給您的網站。如要驗證使用者，必須進行部分伺服器端變更，才能接收及驗證 ID 權杖。

使用者體驗注意事項

您通常需要在自己的來源中新增 HTTP 端點，才能處理伺服器端的回應。以下因素可能會影響產生的使用者體驗。

是否觸發「One Tap」或「使用 Google 帳戶登入」功能。
使用的是 HTML API 或 JavaScript API。
指出用來處理回應的登入 URI 或 JavaScript 回呼函式。

以下說明您實際取得的使用者體驗。

針對「使用 Google 帳戶登入」按鈕重新導向使用者體驗模式：
- 無論使用的是 HTML API 或 JavaScript API，您都必須設定登入 URI。由於使用者已經離開您的網頁，因此無法使用 JavaScript 回呼函式處理回應。
- 使用者體驗摘要：使用者點選「使用 Google 帳戶登入」按鈕後，會看到整頁重新導向至 Google UI，讓使用者選取及核准工作階段。完成後，系統會將整頁的 POST 提交至您指定的登入 URI。
如果使用 JavaScript API，或是使用了 HTML API 並提供 JavaScript 回呼函式，則採用「One Tap」或「使用 Google 帳戶登入」按鈕的彈出式使用者體驗模式：
- 驗證回應會傳回 JavaScript 回呼函式。
- 使用者體驗摘要：One Tap 提示或彈出式視窗會顯示在網頁上方。使用者在提示或彈出式視窗內完成使用者體驗選擇及核准程序後，JavaScript 回呼函式會收到回應。後續的使用者體驗將由回呼函式提交回應至伺服器的方式決定。
重點：如要在不重新載入網頁的情況下進行驗證，常見的做法是透過 JavaScript 回呼函式接收驗證回應，然後透過 XmlHttpRequest 將其提交至伺服器。
重點提示：如要自行採取安全措施，您可以接收 JavaScript 回呼函式提供的驗證回應，然後使用網站所需的其他參數來提交這類回應。
否則 (包含登入 URI 案例的 HTML API)：
- 驗證回應會提交至登入 URI。
- 使用者體驗摘要：One Tap 提示或彈出式視窗會顯示在網頁上方。使用者在選取及核准工作階段的提示或彈出式視窗中完成使用者體驗後，系統就會使用整頁 POST 提交功能，將驗證回應提交至您指定的登入網址。

建議您採用一致的方式提交 One Tap 回應和「使用 Google 帳戶登入」按鈕回應。

安全性考量

為了防範跨網站偽造要求攻擊：

如果是 Google Identity 服務用戶端 JavaScript 程式庫觸發的貼文提交作業，您可以使用內建的雙提交 Cookie 模式。詳情請參閱「驗證伺服器端的 Google ID 權杖」一節。
如果要透過 XmlHttpRequest 提交自己的來源，您可以使用自訂 HTTP 標頭或安全團隊核准的其他安全性措施。

如要在驗證回應中驗證 ID 權杖，強烈建議您針對平台使用 Google API 用戶端程式庫，或一般用途 JWT 程式庫。

常見問題 (FAQ)

網頁畫面是否提供 One Tap 和「使用 Google 帳戶登入」按鈕？

否。基於安全考量，使用者不應將 Google 工作階段新增至 WebView。因此，由於不會納入 Google 工作階段，因此在 WebView 中會停用 GIS。
可以使用自己的「使用 Google 帳戶登入」按鈕嗎？不需要。透過 OAuth 伺服器端流程或舊版 Google 登入 JavaScript 程式庫，供應商可以使用《登入品牌宣傳指南》建立自己的 Google 登入按鈕版本。

不過，「使用 Google 帳戶登入」功能已移除這項功能。所有「使用 Google 帳戶登入」按鈕都必須由 Google Identity Services JavaScript 程式庫產生。造成這項異動的原因有兩個，
- 有些依賴方由於違反指南規定，因此網站上的「使用 Google 帳戶登入」按鈕會不一致。
- 使用程式庫產生時，您不需要在登入品牌宣傳指南本身有所變更時進行任何變更。
為了強制執行這項規則，JavaScript 程式庫只會公開用來轉譯按鈕的 API，但不會公開用來啟動登入流程的 API。
如果我的網站只啟用 One Tap，但未啟用「使用 Google 帳戶登入」按鈕，會怎麼樣？

建議您在網站上同時使用 One Tap 和「使用 Google 帳戶登入」按鈕。由於指數等待期的緣故，系統可能不會每次都顯示 One Tap。如果使用者確實希望以 Google 帳戶登入您的網站，他們可以前往主要的登入對話方塊，然後透過「使用 Google 帳戶登入」按鈕登入。使用「使用 Google 帳戶登入」按鈕成功登入後，系統會清除 One Tap 等待期，讓 One Tap 能顯示下次登入時，Google 提供的其他按鈕流程無法清除 One Tap 等待期狀態，因為這些按鈕位於不同的 JavaScript 二進位檔中。

如果網站只啟用 One Tap，但未啟用「使用 Google 帳戶登入」按鈕，您可能會看見 One Tap 流程的效能下滑，因為指數等待期不會及時清除。
系統何時剖析我的 HTML API 程式碼？我日後可以變更 HTML API 程式碼嗎？

Google Identity Services JavaScript 程式庫會剖析並執行您的 HTML API 程式碼，這可以是 JavaScript 程式庫載入事件或 DomContentLoaded 事件，以較晚者為準。
- 如果在載入 JavaScript 程式庫時觸發 DomContentLoaded 事件，系統會立即剖析並執行您的 HTML API 程式碼。
- 否則，JavaScript 程式庫會為 DomContentLoaded 事件加入事件監聽器。觸發之後，事件監聽器會剖析並執行 HTML API 程式碼。
另請注意，HTML API 程式碼的剖析和執行是一次性的。
- 剖析和執行後，系統會忽略您對 HTML API 程式碼所做的任何後續變更。
- 開發人員無法使用任何 API 觸發剖析或執行程序。
提示： 如果上述行為不符合您的需求，請使用 JavaScript API。