Google Identity 服務即將遷移至 FedCM API。請參閱遷移指南，瞭解有哪些可能的變更，避免使用者登入網站受到負面影響。

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

整合注意事項

本逐步指南可協助您針對所有主要整合問題做出決策。

摘要中使用 Google 帳戶登入

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

使用者登入 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 會自動選取唯一的工作階段，因此會略過帳戶選擇器頁面。
- 「使用 Google 帳戶登入」按鈕會保留在帳戶選擇器頁面，方便使用者在需要時新增 Google 工作階段。
如果所選 Google 帳戶未曾與網站連結，或是權限已遭到撤銷，系統會顯示同意聲明頁面。

核准後，Google 會記錄這項決定，以便在下次跳過同意聲明頁面。
使用 JavaScript 回呼處理常式或向後端服務提交的文章，即可分享包含使用者名稱、電子郵件地址和個人資料相片的 JSON Web Token (也稱為 ID 權杖) 憑證。

將 ID 權杖傳回至用戶端端的 JavaScript 回呼處理常式，目的並非讓您在 JavaScript 程式碼中解碼，而是讓您以自己的方式將其提交至伺服器。一個很好的例子是使用 XmlHttpRequest，避免因提交文章而導致網頁重新載入。

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

您將在自己的網站上管理使用者的登入狀態。

使用者的 Google 帳戶登入狀態和您的應用程式是獨立的，除非您知道使用者已成功驗證並登入 Google 帳戶，否則這兩者之間沒有關聯。使用者可以保持登入狀態、登出，或切換至其他 Google 帳戶，同時在您的網站上維持有效的登入工作階段。

總而言之，與密碼登入方式一樣，使用 Google 帳戶登入提供另一種驗證網頁使用者身分的做法。在驗證後，「使用 Google 帳戶登入」功能不會提供任何網站工作階段管理功能。

存取 Google API 和服務

如前文所述，即使您已整合驗證 API，如果網站需要代表已驗證的使用者存取 Google API 和服務，可能還需要整合授權 API。驗證會為網站提供 ID 權杖，用於驗證使用者；授權則會為網站提供 (個別) 存取權杖和權限，以便使用 Google API 和服務。詳情請參閱「授權使用網頁」。

驗證和授權的使用者體驗分離

如果網站需要同時呼叫驗證和授權 API，您必須在不同時間分別呼叫這兩種 API。請參閱「分開驗證和授權時機」。

如果您的網站先前曾同時要求驗證和授權權杖，在使用 Google Identity 服務 JavaScript 程式庫時，您需要調整使用者體驗，將驗證時刻和授權時刻分開。

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

為了提供順暢的使用者體驗轉換體驗，並降低複雜度，一般做法是將程序分為兩個步驟。

重構使用者體驗，將驗證和授權階段分開。
改用 Google Identity 服務 JavaScript 程式庫。

重點： 我們將在後續說明驗證時機 API 和相關功能。如要瞭解授權時刻 API 和功能，請參閱授權 API 說明文件。

HTML API 與 JavaScript API

您可以使用 HTML API 或 JavaScript API，將「輕觸一次」按鈕、「自動登入」按鈕或「使用 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 帳戶登入」按鈕。例如，使用者在選單中選取「登入」後。
多次呼叫 API。舉例來說，每次顯示登入對話方塊時，都需要轉譯「使用 Google 帳戶登入」按鈕。
動態產生 HTML 網頁，因此很難在其中嵌入 API 呼叫程式碼。
您在較晚的時間載入 Google Identity 服務 JavaScript 程式庫。

在頁面 onload 事件或 Google Identity Services JavaScript 程式庫 onload 事件中，HTML API 程式碼只能叫用一次 (以較晚發生的事件為準)。如果 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 和按鈕轉譯使用；這些 API 沒有對應的 HTML API：

「使用 Google 帳戶登入」按鈕的考量

本節將說明在網站中整合「使用 Google 帳戶登入」按鈕時應考量的事項。

彈出式視窗與重新導向

OAuth 2.0 規格考量了 HTTP 重新導向，但缺乏顯示彈出式對話方塊的相關指引。彈出式使用者體驗 (尤其是在電腦網站上) 可能會為使用者提供更優質的使用者體驗。這是因為使用者不會從第三方網頁重新導向，且對話方塊式彈出式視窗會提供相關內容的權限授予體驗。

使用彈出式使用者體驗時，識別資訊提供者需要在用戶端端跨來源通訊管道上建構，才能將 OAuth 回應從彈出式視窗 (顯示識別資訊提供者的同意頁面) 傳遞至主要視窗 (顯示第三方網頁)。通常，您需要在兩端使用 JavaScript 程式碼，才能在視窗之間傳送及接收 OAuth 回應。

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

使用「Sign in with Google」按鈕的重新導向流程與 OAuth 重新導向流程之間存在一些差異。

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

對於使用 HTML API 的開發人員，無論使用哪種使用者體驗，憑證一律會透過 POST 方法和相同的參數，提交至 data-login_uri。這樣一來，您就能在不變更其他程式碼的情況下切換 UX 模式。針對重新導向使用者體驗，data-login_uri 必須新增至 Google API 控制台中用戶端的已授權的重新導向 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 服務 JavaScript 程式庫。建議先載入 JavaScript 程式庫，再載入其他大型程式庫，尤其是在行動網頁上。
如果「使用 Google 帳戶登入」按鈕僅在使用者從選單中選取「登入」後才顯示。您可以先在隱藏元素中顯示「使用 Google 帳戶登入」按鈕，然後在使用者從選單中選取「登入」後，將按鈕顯示出來。

重點提示： 請盡早載入 Google Identity 服務 JavaScript 程式庫，盡可能減少顯示「使用 Google 帳戶登入」按鈕的延遲時間。

One Tap 考量事項

自動登入

如果使用者先前已授予網站權限，自動登入功能可讓使用者不必點選 One Tap 提示，即可登入網站。

可取消的自動登入功能具備下列優點：

這可能會節省使用者的一項動作，進而提升登入率。
與先前已淘汰的 Google 登入 JavaScript 程式庫提供的靜默登入功能不同，在自動登入時，使用者一律會看到某些 UI，讓他們瞭解為何以及如何登入您的網站。使用者也可以視需要取消訂閱。
系統會自動選取使用者先前使用的帳戶，這可能會防止使用者在您的網站上建立重複的帳戶。

您需要根據網站的使用者體驗和業務需求，決定是否要啟用自動登入功能。尤其是如果網站的大部分登出情形都是因為工作階段逾時，而非使用者明確選擇登出所致，自動登入功能可能會是使用者恢復工作階段狀態的好方法。

顯示 One Tap UI 的時機

使用 HTML API 時，One Tap 一律會在網頁載入時顯示。您可以使用 JavaScript API 控制 One Tap UI 的顯示時機。請注意，由於以下原因，One Tap UI 不一定會在叫用 API 後顯示。

瀏覽器中沒有有效的 Google 工作階段。
所有有效的 Google 工作階段都已停用。
冷卻中。

請勿嘗試在按鈕點擊事件中只顯示 One Tap UI。由於上述原因，One Tap UI 可能不會顯示，使用者可能會因為在使用者操作後沒有任何顯示內容而體驗到不良的使用者體驗。在按鈕點擊事件中：

建議

顯示登入對話方塊，其中包含密碼登入和「使用 Google 帳戶登入」按鈕，並同時呼叫 One Tap API。這樣一來，使用者就能隨時透過某種方式登入您的網站。

不建議使用

如果只提供 One Tap，使用者可能會遇到 One Tap 未顯示的登入問題。
如果 One Tap 未顯示，請使用 UI 狀態回呼來顯示其他 UI。我們不建議使用這項功能，因為 UI 狀態回呼可能無法與日後版本的聯合憑證管理搭配使用。

在 ITP 瀏覽器上使用 One Tap

由於智慧防追蹤功能 (ITP)，一般 One Tap 使用者體驗無法在 ITP 瀏覽器上運作，例如 iOS 版 Chrome、Safari 和 Firefox。這些瀏覽器會改為提供以歡迎頁面為開端的不同使用者體驗。

您可以視需要停用 ITP 瀏覽器上的 One Tap 使用者體驗。詳情請參閱「ITP 瀏覽器上的 One Tap 支援功能」。

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

如果使用者點選離開，則取消提示

根據預設，如果使用者點選提示訊息外，One Tap 提示訊息就會自動關閉。您可以視需要變更這項行為。

建議您在電腦版網站上保持 One Tap 提示開啟狀態，因為螢幕大小足夠大。

變更 One Tap UX 的位置

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

變更登入內容

One Tap 應是網站中更大使用者體驗流程的一部分。根據預設，One Tap UI 會在登入情境中使用。UI 中的語言包含特定用詞，例如「sign in」。您可以變更內容屬性，建立不同的詞組。您可以選取最適合使用者體驗流程的 One Tap 標頭。

背景資訊
`signin`	「使用 Google 帳戶登入」
`signup`	「使用 Google 帳戶註冊」
`use`	「與 Google 服務整合」

監聽 One Tap UI 狀態

為了能順暢整合至更大的使用者體驗流程，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 流程。

在這種情況下，系統會根據您的工作階段 Cookie 狀態，而非網頁中是否有 One Tap HTML API 程式碼，決定是否觸發 One Tap 流程。

伺服器端整合

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

使用者體驗考量

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

系統是否觸發 One Tap 或使用 Google 帳戶登入。
是否使用 HTML API 或 JavaScript API。
是否使用登入 URI 或 JavaScript 回呼函式來處理回應。

您實際獲得的使用者體驗如下所述。

針對「使用 Google 帳戶登入」按鈕的重新導向使用者體驗模式：
- 無論您使用 HTML API 還是 JavaScript API，都必須設定登入 URI。使用者已從網頁重新導向，因此無法使用 JavaScript 回呼函式處理回應。
- UX 摘要：使用者按一下「使用 Google 帳戶登入」按鈕後，會看到全頁重新導向至 Google UI，以便選取及核准工作階段。完成後，系統會將整頁 POST 提交至您指定的登入 URI。
如果使用 JavaScript API 或 HTML API，並提供 JavaScript 回呼函式，則針對 One Tap 或「使用 Google 帳戶登入」按鈕彈出式使用者介面模式：
- 系統會將驗證回應傳回至 JavaScript 回呼函式。
- UX 摘要：網頁上方會顯示 One Tap 提示或彈出式視窗。使用者在提示或彈出式視窗中完成會話方塊選取和核准的使用者體驗後，JavaScript 回呼函式就會收到回應。後續的使用者體驗取決於回呼函式如何將回應提交至伺服器。
重點提示：如要在不重新載入網頁的情況下進行驗證，一般做法是透過 JavaScript 回呼函式接收驗證回應，然後使用 XmlHttpRequest 將其提交至伺服器。
重點提示：如要強制執行自己的安全措施，您可以透過 JavaScript 回呼函式接收驗證回應，然後將其連同網站所需的其他參數提交。
否則 (HTML API 搭配登入 URI 的情況)：
- 驗證回應會提交至登入 URI。
- UX 摘要：網頁上方會顯示 One Tap 提示或彈出式視窗。使用者在提示或彈出式視窗中完成工作階段選取和核准的使用者體驗後，系統會使用全頁 POST 提交至您指定的登入網址，以便提交驗證回應。

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

安全性考量

如要防範跨網站要求偽造攻擊，

如果是 Google 身分識別服務用戶端 JavaScript 程式庫觸發的郵件提交作業，您可以使用內建的雙重提交 Cookie 模式。詳情請參閱「在伺服器端驗證 Google ID 權杖」。
如要使用 XmlHttpRequest 提交至自己的來源，您可以使用自訂 HTTP 標頭或安全團隊核准的其他安全措施。

如要驗證驗證回應中的 ID 權杖，強烈建議您使用平台的 Google API 用戶端程式庫，或通用 JWT 程式庫。

常見問題 (FAQ)

網頁檢視畫面中是否有 One Tap 和「使用 Google 帳戶登入」按鈕？

否。基於安全考量，使用者不應將 Google 工作階段加入 Webview。因此，GIS 會在 WebView 中停用，因為 Google 工作階段不應出現在其中。
我可以使用自己的「使用 Google 帳戶登入」按鈕嗎？否。使用 OAuth 伺服器端流程或舊版 Google 登入 JavaScript 程式庫時，依附元件方可以根據「登入品牌化指南」建立自己的 Google 登入按鈕。

不過，使用 Google 帳戶登入已移除這項功能。所有「使用 Google 帳戶登入」按鈕都必須由 Google Identity 服務 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 程式庫會在 JavaScript 程式庫載入事件或 DomContentLoaded 事件 (以較晚者為準)剖析及執行 HTML API 程式碼。
- 如果在載入 JavaScript 程式庫時觸發 DomContentLoaded 事件，HTML API 程式碼會立即剖析及執行。
- 否則，JavaScript 程式庫會為 DomContentLoaded 事件新增事件監聽器。觸發時，事件監聽器會剖析及執行 HTML API 程式碼。
另請注意，HTML API 程式碼的剖析和執行作業是分開進行。
- 剖析及執行完成後，系統會忽略 HTML API 程式碼的後續變更。
- 開發人員無法使用 API 觸發剖析或執行程序。
提示： 如果上述行為無法滿足您的需求，請使用 JavaScript API。