這份逐步指南可協助您對所有主要整合問題做出決策。
「使用 Google 帳戶登入」摘要
以下是使用者在網站上登入 / 註冊的一般步驟。
使用者會登入 Google 網站。
為確保「使用 Google 帳戶登入」功能正常運作，瀏覽器應具備運作中的 Google 工作階段。只有在使用者先登入 Google 再載入您的網頁時，才會觸發 One Tap 和自動登入功能。這個步驟對於「使用 Google 帳戶登入」按鈕流程為選用，因為當使用者按下按鈕時，系統會提示使用者登入 Google。
使用者瀏覽網頁時，如果嵌入了 One Tap、自動登入或「使用 Google 帳戶登入」按鈕，
使用者會與 One Tap、「使用 Google 帳戶登入」按鈕和後續使用者體驗流程互動，例如：
- 如要繼續操作，請選取執行中的 Google 工作階段。
- 徵得使用者同意 (如果尚未同意)，與您的網站分享個人資料。
如果瀏覽器中只有一個運作中的 Google 工作階段，
- One Tap 會自動選取唯一的工作階段，因此略過帳戶選擇工具頁面。
- 「使用 Google 帳戶登入」按鈕會持續顯示在帳戶選擇工具頁面上，可讓使用者視需要新增 Google 工作階段。
如果網站未曾與所選 Google 帳戶搭配使用，或是權限已遭撤銷，系統會顯示同意頁面。
核准後，Google 會記錄做出決定，以便下次略過同意聲明頁面。
系統會使用 JavaScript 回呼處理常式或提交至後端服務的貼文，分享含有使用者名稱、電子郵件和個人資料相片的 JSON Web Token (也稱為 ID 權杖) 憑證。
在用戶端將 ID 權杖傳回至 JavaScript 回呼處理常式的目的，並非在 JavaScript 程式碼中解碼，而是要自行以自己的方式提交至伺服器。例如，使用 XmlHttpRequest 可避免因提交貼文而重新載入頁面。
在伺服器端，系統會驗證 Google 核發的 JWT 憑證，並會使用該憑證來建立新帳戶或在您的網站上建立經過驗證的工作階段。
您將在自己的網站上管理使用者的登入狀態。
使用者的 Google 帳戶登入狀態和您的應用程式相互獨立，但如果您知道使用者已成功驗證並登入 Google 帳戶，則在登入當下本身。使用者可能會維持登入狀態、登出或改用其他 Google 帳戶，同時在您的網站上保持登入狀態。
總結來說，如同密碼式登入，使用 Google 帳戶登入功能提供了另一種在網路上驗證使用者的方式。通過驗證後，「使用 Google 帳戶登入」功能不會為網站上的工作階段管理提供任何功能。
存取 Google API 和服務
即使您已按照上述方式整合 Auth API，若您的網站需要代表已驗證使用者存取 Google API 和服務，您可能還需要整合授權 API。雖然驗證程序可提供網站 ID 權杖來驗證使用者，但授權會讓網站取得 (獨立) 的存取權杖和使用 Google API 和服務的權限。詳情請參閱授權網頁版。
區隔驗證和授權的使用者體驗區隔
如果您的網站需要同時呼叫驗證和授權 API，您必須在不同的時機分別呼叫這些 API。請參閱區隔驗證與授權時刻。
如果您的網站過去曾同時要求驗證和授權權杖，那麼在使用 Google Identity 服務 JavaScript 程式庫時，您必須調整使用者體驗來區隔驗證時間與授權時間。
- 在驗證階段，您的網站可以整合 One Tap、自動登入或「使用 Google 帳戶登入」按鈕，讓使用者登入或註冊您的網站。
- 在授權階段時，您的網站可以叫用授權 API，藉此取得存取 Google API 或服務的權限和權杖。
為了順利轉換使用者體驗並降低複雜程度，常見的做法是將程序分成兩個分隔的步驟。
- 重構使用者體驗，將驗證與授權程序分開。
遷移至 Google Identity Services JavaScript 程式庫。
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 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。
請勿在相同網頁中透過 JavaScript API 使用 HTML 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 帳戶登入」按鈕支援彈出式和重新導向的使用者體驗。
根據預設，系統會使用彈出式 UX。您可以設定 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 程式庫，再載入其他大型程式庫 (特別是在行動版網站上)。
如果「使用 Google 帳戶登入」按鈕只有在使用者從選單中選取「Login」後才會顯示。您可以先在隱藏的元素中顯示「使用 Google 帳戶登入」按鈕，然後在使用者從選單中選取「Login」後，再顯示該按鈕。
One Tap 注意事項
自動登入
可取消的自動登入功能有以下優點。
- 儲存單一使用者動作或許可以提高登入率。
- 與先前已淘汰的 Google 登入 JavaScript 程式庫所提供的無訊息登入不同，使用者一律會在自動登入時看到某些使用者介面，因此就能瞭解登入網站的原因和方式。使用者也可以視需要取消。
- 系統會自動選取使用者先前使用的帳戶，避免使用者在您的網站上建立重複的帳戶。
您必須根據網站的使用者體驗和業務需求，決定是否要啟用自動登入。尤其是，如果大部分網站登出作業是由工作階段逾時 (而非使用者明確的選擇) 引起，自動登入或許是讓使用者復原工作階段狀態的好方法。
One Tap UI 顯示時機
如果使用 HTML API，載入網頁時一律顯示 One Tap。這個 JavaScript API 可讓您控制 One Tap UI 的顯示時機。請注意，基於以下部分原因，叫用 API 後 One Tap UI 可能不會一律顯示。
請勿嘗試在按鈕點擊事件中只顯示 One Tap UI。One Tap UI 可能因為上述原因無法顯示，而使用者的使用者體驗也可能因此毀損，因為使用者操作後就看不到任何內容。點按按鈕點擊事件：
建議
- 顯示含有密碼登入和「使用 Google 帳戶登入」按鈕的登入對話方塊，並同時呼叫 One Tap API。這能確保使用者始終能取得您網站的某種登入方式。
不建議使用
- 如果您只提供 One Tap，如果未顯示 One Tap，使用者可能會遇到登入體驗中斷的問題。
- 如果 One Tap 未顯示畫面，請使用 UI 狀態回呼顯示其他 UI。不建議這麼做，因為日後推出的版本，UI 狀態回呼可能不適用於聯合憑證管理。
One Tap 在 ITP 瀏覽器中
由於智慧防追蹤功能 (ITP)，一般的 One Tap 使用者體驗無法在 ITP 瀏覽器上運作，例如 iOS 版 Chrome、Safari 和 Firefox。這些瀏覽器會提供不同的使用者體驗，從歡迎頁面開始。
如有需要，您可以停用 ITP 瀏覽器的 One Tap 使用者體驗。詳情請參閱「ITP 瀏覽器的 One Tap 支援」。
無法在非 ITP 瀏覽器中啟用這項使用者體驗，例如 Android/macOS/Linux 和 Edge 上的 Chrome。
如果使用者點選離開，請取消提示
根據預設，如果使用者點選提示以外的提示，One Tap 提示會自動關閉。如有需要，您可以變更這項行為。
由於螢幕大小夠大，因此建議您在電腦上將 One Tap 提示保持開啟。
變更 One Tap 使用者體驗的位置
在電腦版網站上，您可以變更 One Tap 提示的位置。 不過，由於日後推出的版本聯合憑證管理不支援這項功能，因此不建議使用這項功能。
變更登入內容
One Tap 應提供網站整體使用者體驗流程中的一環，根據預設，系統會在登入期間使用 One Tap UI。UI 中的語言含有特定的用詞，例如「登入」。您可以變更結構定義屬性，以建立一組不同的用詞您可以選取最適合您使用者體驗流程的 One Tap 標頭。
| 脈絡 | |
|---|---|
signin |
「使用 Google 帳戶登入」 |
signup |
註冊 Google |
use |
「與 Google 搭配使用」 |
監聽 One Tap UI 狀態
為了與更大規模的使用者體驗流程完美整合，One Tap 可在 UI 狀態變更時通知您。不過，未來的聯合憑證管理版本不支援這項功能。
點選一次即可瀏覽所有子網域
根據預設，系統會追蹤每個來源的 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。
針對 One Tap 或「使用 Google 帳戶登入」按鈕的彈出式使用者體驗模式 (如果使用的是 JavaScript API，或是系統使用 HTML API，且提供了 JavaScript 回呼函式)：
- 驗證回應會傳遞回 JavaScript 回呼函式。
- 使用者體驗摘要：網頁上方顯示的 One Tap 提示或彈出式視窗。使用者在選取及核准工作階段的提示或彈出式視窗中完成使用者體驗後，JavaScript 回呼函式會收到回應。後續使用者體驗是由回呼函式如何將回應提交至伺服器的方式決定。
其他情況 (或 HTML API 的登入 URI 案例)：
- 驗證回應會提交至登入 URI。
- 使用者體驗摘要：網頁上方顯示的 One Tap 提示或彈出式視窗。使用者在選擇及核准工作階段時，在提示或彈出式視窗完成使用者體驗後，系統會使用整頁的
POST提交內容至您指定的登入網址，提交驗證回應。
建議您以一致的方式提交 One Tap 回應和「使用 Google 帳戶登入」按鈕回應。
安全性考量
為防範跨網站偽造要求攻擊，
- 對於由 Google Identity 服務用戶端 JavaScript 程式庫觸發的提交貼文，您可以使用內建的雙重提交 Cookie 模式。詳情請參閱「驗證伺服器端的 Google ID 權杖」一文。
- 如要透過 XmlHttpRequest 提交內容，您可以使用自訂 HTTP 標頭，或是安全性團隊核准的其他安全措施。
如要在驗證回應中驗證 ID 權杖，強烈建議您針對平台使用 Google API 用戶端程式庫，或一般用途的 JWT 程式庫。
常見問題 (FAQ)
WebView 是否提供 One Tap 和「使用 Google 帳戶登入」按鈕？
否。基於安全考量，使用者不應將 Google 工作階段新增到 WebView。因此 WebView 中已停用 GIS，因為其中沒有任何 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 可觸發剖析或執行程序。