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

從 Google 登入遷移

本指南可協助您瞭解成功遷移 JavaScript 程式庫所需的變更和步驟，將舊版 Google 登入平台資料庫遷移至新版 Google Identity 服務資料庫，以便進行驗證。

如果您的用戶端使用的是適用於 JavaScript 的 Google API 用戶端程式庫或其他舊版程式庫來進行授權，請參閱「遷移至 Google 身分識別服務」一文，瞭解詳情。

驗證及授權

驗證可確認使用者身分，通常稱為使用者註冊或登入。授權是指授予或拒絕資料或資源存取權的程序。舉例來說，您的應用程式要求使用者同意存取其 Google 雲端硬碟。

與先前的 Google 登入平台資料庫一樣，新的 Google Identity 服務資料庫也同時支援驗證和授權程序。

不過，新版程式庫會將這兩個程序分開，以便開發人員將 Google 帳戶與應用程式整合，降低複雜度。

如果您的用途僅與驗證相關，請繼續閱讀本頁內容。

如果您的用途包括授權，請參閱「使用者授權的運作方式」和「遷移至 Google 身分識別服務」，確保應用程式使用全新且經過改善的 API。

異動情形

對於使用者而言，新的 Google Identity 服務程式庫提供許多可用性改善功能。主要包含：

新的低摩擦 One Tap 和自動登入流程，可減少個別步驟
更新的登入按鈕，提供使用者個人化體驗
在網路上提供一致的品牌形象和登入行為，有助於提升使用者對服務的理解和信任度。
快速取得內容；使用者可直接在網站上的任何位置註冊及登入，無須先前往登入或帳戶頁面。

對於開發人員而言，我們一直致力於降低複雜度、提升安全性，並盡可能加快整合作業。其中一些改善項目包括：

使用 HTML 將使用者登入功能加入網站的靜態內容，
將登入驗證與授權和使用者資料分享分開，這樣您就不需要整合 OAuth 2.0，也能讓使用者登入網站，
我們仍支援彈出式和重新導向模式，但 Google 的 OAuth 2.0 基礎架構現在會重新導向至後端伺服器的登入端點。
將先前 Google 身分和 Google API JavaScript 程式庫的功能整合到單一新程式庫中，
針對登入回應，您現在可以決定是否要使用Promise，且為了簡化操作，我們已移除透過 getter 樣式函式進行的間接操作。

登入遷移範例

如果您要從現有的 Google 登入按鈕遷移，且只想讓使用者登入網站，最簡單的做法就是更新為新的個人化按鈕。您可以換用 JavaScript 程式庫，並更新程式碼庫，以便使用新的登入物件。

程式庫和設定

您不再需要使用舊版 Google 登入平台程式庫：apis.google.com/js/platform.js，以及JavaScript 適用的 Google API 用戶端程式庫：gapi.client，已由單一新的 Google Identity 服務 JavaScript 程式庫取代：accounts.google.com/gsi/client。

前面提到的三個 JavaScript 模組：用於登入的 api、client 和 platform，都是從 apis.google.com 載入。以下列出網站中可能包含舊版程式庫的常見位置：

預設登入按鈕會載入 apis.google.com/js/platform.js，
載入自訂按鈕圖片 apis.google.com/js/api:client.js，
直接使用 gapi.client 會載入 apis.google.com/js/api.js。

在多數情況下，您可以繼續使用現有的網頁應用程式用戶端 ID 憑證。在遷移過程中，建議您查看 OAuth 2.0 政策，並使用 Google API 控制台確認並視需要更新下列用戶端設定：

測試版和正式版應用程式使用不同的專案，且各自有專屬的用戶端 ID。
OAuth 2.0 用戶端 ID 類型為「Web application」，且
HTTPS 適用於已授權的 JavaScript 來源和重新導向 URI。

找出受影響的程式碼並進行測試

偵錯 Cookie 可協助您找出受影響的程式碼，並測試淘汰後的行為。

在大型或複雜的應用程式中，您可能很難找出所有受 gapi.auth2 模組淘汰影響的程式碼。如要將即將淘汰的功能現有用途記錄到控制台，請將 G_AUTH2_MIGRATION 的 Cookie 值設為 informational。您可以選擇在半形冒號後加上鍵值，以便將記錄資料也儲存到工作階段儲存空間。在登入並收到憑證後，檢查或將收集到的記錄傳送至後端，以利日後分析。舉例來說，informational:showauth2use 會將來源和網址儲存至名為 showauth2use 的工作階段儲存空間鍵。

如要驗證 gapi.auth2 模組不再載入時的應用程式行為，請將 G_AUTH2_MIGRATION Cookie 的值設為 enforced。這樣一來，您就能在淘汰日期前測試淘汰後的行為。

可能的 G_AUTH2_MIGRATION Cookie 值：

enforced 不載入 gapi.auth2 模組。
informational 將已淘汰功能的使用情形記錄到 JS 控制台。設定選用金鑰名稱 (informational:key-name) 時，也會將記錄資料寫入工作階段儲存空間。

為盡量減少對使用者的影響，建議您先在開發和測試期間在本機設定此 Cookie，再將其用於正式環境。

HTML 和 JavaScript

在這個僅限驗證的登入情境中，系統會顯示現有 Google 登入按鈕的範例程式碼和算繪。請從彈出式視窗或重新導向模式中選取，瞭解透過 JavaScript 回呼或安全重新導向至後端伺服器登入端點，處理驗證回應的方式有何不同。

舊做法

算繪 Google 登入按鈕，並使用回呼直接透過使用者的瀏覽器處理登入作業。

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

重新導向模式

算繪 Google 登入按鈕，並結束使用者瀏覽器對後端伺服器登入端點的 AJAX 呼叫。

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

最終顯示的內容

新的視覺屬性可簡化先前建立自訂按鈕的方法，並可避免呼叫 gapi.signin2.render()，也無需在網站上代管及維護圖片和視覺資產。

Google 登入

Google 已登入

使用者登入狀態更新按鈕文字。

新做法

如要在僅驗證的登入情境中使用新程式庫，請從彈出式視窗或重新導向模式中選取，然後使用程式碼範例取代登入頁面上的現有實作。

使用回呼，直接透過使用者的瀏覽器處理登入作業。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

重新導向模式

Google 會根據 data-login_url 屬性指定的登入端點，呼叫您的登入端點。先前，您負責處理 POST 作業和參數名稱。新的程式庫會透過 credential 參數將 ID 權杖發布至端點。最後，請在後端伺服器上驗證 ID 權杖。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

最終顯示的內容

使用 visual-attributes 自訂「使用 Google 帳戶登入」按鈕的大小、形狀和顏色。顯示 One Tap 彈出式視窗和個人化按鈕，提升登入率。

One Tap 彈出式視窗

使用者登入狀態未將按鈕文字從「Sign in」更新為「Signed in」。取得同意後，或在使用者再次造訪時，個人化按鈕會顯示使用者的名稱、電子郵件和個人資料相片。

在這個僅限驗證的範例中，新的 accounts.google.com/gsi/client 程式庫、g_id_signin 類別和 g_id_onload 物件會取代先前的 apis.google.com/js/platform.js 程式庫和 g-signin2 物件。

除了轉譯新的個人化按鈕，範例程式碼也會顯示新的 One Tap 彈出式視窗。無論您在何處顯示個人化按鈕，都強烈建議您一併顯示 One Tap 彈出式視窗，以便在使用者註冊和登入時盡量減少摩擦。

雖然這麼做會增加登入的摩擦力，因此不建議採用，但新的個人化按鈕可以單獨顯示，不必同時顯示 One Tap 對話方塊。如要這樣做，請將 data-auto_prompt 屬性設為 false。

HTML 和 JavaScript API

上一個範例說明如何使用新的 HTML API，在網站中加入登入功能。或者，您可以使用功能相當的 JavaScript API，或在網站上混合使用 HTML 和 JavaScript API。

如要以互動方式查看按鈕自訂選項 (例如回呼類型) 和屬性 (例如顏色、大小、形狀、文字和主題)，請查看我們的程式碼產生器。可用於快速比較不同的選項，並產生可用於網站的 HTML 程式碼片段。

從任何頁面使用 One Tap 登入

One Tap 是一種新的低摩擦方式，可讓使用者註冊或登入您的網站。這項功能可讓您直接在網站上的任何網頁中啟用使用者登入功能，使用者不必前往專屬的登入頁面。換句話說，這項功能可讓使用者在登入頁面以外的頁面靈活註冊及登入，進而減少註冊和登入的障礙。

如要啟用任何網頁的登入功能，建議您在整個網站的共用頁首、頁尾或其他物件中加入 g_id_onload。

此外，建議您只在登入或使用者帳戶管理頁面中加入 g_id_signin，以便顯示個人化的登入按鈕。將按鈕與其他聯合身分識別提供者按鈕和使用者名稱和密碼輸入欄位一併顯示，讓使用者選擇註冊或登入。

權杖回應

使用者登入時，您不再需要瞭解或使用 OAuth 2.0 授權碼、存取權杖或更新權杖。而是使用 JSON Web Token (JWT) ID 權杖來分享登入狀態和使用者個人資料。為了進一步簡化，您不再需要使用「getter」樣式的存取方法來處理使用者設定檔資料。

安全的 Google 簽署 JWT ID 權杖憑證會在以下情況下傳回：

傳送至使用者在彈出式視窗模式中的瀏覽器 JavaScript 回呼處理常式，或
當「使用 Google 帳戶登入」按鈕 ux_mode 設為 redirect 時，系統會透過 Google 重新導向至您的後端伺服器。

無論是哪種情況，請更新現有的回呼處理常式，方法是移除：

撥打至 googleUser.getBasicProfile()，
對 BasicProfile 的參照，以及對 getId()、getName()、getGivenName()、getFamilyName()、getImageUrl()、getEmail() 方法的相關呼叫，以及
AuthResponse 物件的用法。

請改為直接參照新 JWT CredentialResponse 物件中的 credential 子欄位，以便處理使用者個人資料。

此外，如果您使用的是重新導向模式，請務必防範跨網站要求偽造 (CSRF)，並在後端伺服器上驗證 Google ID 權杖。

如要進一步瞭解使用者與網站的互動情形，您可以使用 CredentialResponse 中的 select_by 欄位，判斷使用者同意結果和使用的特定登入流程。

使用者同意聲明和撤銷權限

使用者初次登入您的網站時，Google 會提示使用者同意將帳戶個人資料提供給您的應用程式。只有在使用者提供同意聲明後，系統才會透過 ID 權杖憑證酬載，將使用者個人資料提供給您的應用程式。撤銷此設定檔的存取權，等同於撤銷先前登入程式庫中的存取權杖。

使用者可以前往 https://myaccount.google.com/permissions 撤銷權限，並將您的應用程式與 Google 帳戶解除連結。或者，他們也可以觸發您實作的 API 呼叫，直接從您的應用程式中斷線；舊版 disconnect 方法已由新版 revoke 方法取代。

當使用者在您的平台上刪除帳戶時，最佳做法是使用 revoke 將應用程式與使用者的 Google 帳戶解除連結。

先前，auth2.signOut() 可用於協助管理使用者從應用程式登出。您應移除所有 auth2.signOut() 的用途，並直接管理個別使用者的工作階段狀態和登入狀態。

工作階段狀態和 Listener

新的程式庫不會維護網頁應用程式的登入狀態或工作階段狀態。

Google 帳戶的登入狀態、應用程式的會話狀態和登入狀態是不同的概念。

使用者登入 Google 帳戶和您的應用程式狀態彼此獨立，但在登入過程中，您知道使用者已成功驗證並登入 Google 帳戶時，這兩者就會相互關聯。

當您在網站上加入「使用 Google 帳戶登入」、「One Tap 登入」或「自動登入」功能時，使用者必須先登入 Google 帳戶，才能：

在首次註冊或登入網站時，提供同意書分享使用者個人資料
後續您也可以使用這項功能，讓使用者在日後造訪網站時登入。

使用者可以在網站上保持登入狀態、登出或切換至其他 Google 帳戶，同時維持有效的登入工作階段。

您現在必須直接管理網頁應用程式使用者的登入狀態。先前，Google 登入功能可協助監控使用者的工作階段狀態。

移除對 auth2.attachClickHandler() 和其已註冊的回呼處理常式。

先前，事件監聽器用於分享使用者 Google 帳戶登入狀態的變更。不再支援事件監聽器。

移除對 listen()、auth2.currentUser 和 auth2.isSignedIn 的任何參照。

Cookie

「使用 Google 帳戶登入」功能會有限度使用 Cookie，以下說明這些 Cookie。如要進一步瞭解 Google 使用的其他類型 Cookie，請參閱「Google 如何使用 Cookie」。

舊版 Google 登入平台程式庫設定的 G_ENABLED_IDPS Cookie 已不再使用。

新的 Google Identity Services 程式庫可視情況根據您的設定選項，設定下列跨網域 Cookie：

g_state 會儲存使用者的登出狀態，並在使用 One Tap 彈出式視窗或自動登入時設定。
g_csrf_token 是用於防範 CSRF 攻擊的雙重提交 Cookie，會在登入端點呼叫時設定。您可以明確設定登入 URI 的值，也可以讓系統預設為目前網頁的 URI。在使用下列項目時，系統可能會在以下情況下呼叫您的登入端點：
- 使用 data-ux_mode=redirect 的 HTML API，或在設定 data-login_uri 時，或
- 使用 ux_mode=redirect 的 JavaScript API，且未使用 google.accounts.id.prompt() 顯示 One Tap 或自動登入功能。

如果您有管理 Cookie 的服務，請務必在遷移完成後新增兩個 Cookie，並移除舊 Cookie。

如果您管理多個網域或子網域，請參閱「在各子網域中顯示 One Tap」一文，進一步瞭解如何使用 g_state Cookie。

使用者登入功能的物件遷移參考資料

舊	新增	附註
JavaScript 程式庫
apis.google.com/js/platform.js	accounts.google.com/gsi/client	以新內容取代舊內容。
apis.google.com/js/api.js	accounts.google.com/gsi/client	以新內容取代舊內容。
GoogleAuth 物件和相關方法：
GoogleAuth.attachClickHandler()	針對 JS 和 HTML 的 data-callback 使用 IdConfiguration.callback	以新內容取代舊內容。
GoogleAuth.currentUser.get()	CredentialResponse	改用 CredentialResponse，不再需要使用。
GoogleAuth.currentUser.listen()		，即可逐一移除離線觀看清單內的影片；無法取得使用者在 Google 上的目前登入狀態。使用者必須登入 Google 帳戶，才能同意使用服務和登入服務。 CredentialResponse 中的 select_by 欄位可用於判斷使用者同意聲明的結果，以及所使用的登入方式。
GoogleAuth.disconnect()	google.accounts.id.revoke	以新內容取代舊內容。您也可以前往 https://myaccount.google.com/permissions 撤銷授權
GoogleAuth.grantOfflineAccess()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleAuth.isSignedIn.get()		，即可逐一移除離線觀看清單內的影片；無法取得使用者在 Google 上的目前登入狀態。使用者必須登入 Google 帳戶，才能提供同意聲明和登入時刻。
GoogleAuth.isSignedIn.listen()		，即可逐一移除離線觀看清單內的影片；無法取得使用者在 Google 上的目前登入狀態。使用者必須登入 Google 帳戶，才能提供同意聲明和登入時刻。
GoogleAuth.signIn()		，即可逐一移除離線觀看清單內的影片；使用 HTML DOM 載入 g_id_signin 元素，或對 google.accounts.id.renderButton 發出 JS 呼叫，即可觸發使用者登入 Google 帳戶。
GoogleAuth.signOut()		，即可逐一移除離線觀看清單內的影片；應用程式和 Google 帳戶的使用者登入狀態是獨立的。Google 不會管理應用程式的工作階段狀態。
GoogleAuth.then()		，即可逐一移除離線觀看清單內的影片；GoogleAuth 已淘汰。
GoogleUser 物件和相關方法：
GoogleUser.disconnect()	google.accounts.id.revoke	以新內容取代舊內容。您也可以前往 https://myaccount.google.com/permissions 撤銷授權
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile()	CredentialResponse	直接使用 `credential` 和子欄，而非 `BasicProfile` 方法。
GoogleUser.getGrantedScopes()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.getHostedDomain()	CredentialResponse	請改為直接使用 `credential.hd`。
GoogleUser.getId()	CredentialResponse	請改為直接使用 `credential.sub`。
GoogleUser.grantOfflineAccess()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.grant()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.hasGrantedScopes()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.isSignedIn()		，即可逐一移除離線觀看清單內的影片；無法取得使用者在 Google 上的目前登入狀態。使用者必須登入 Google 帳戶，才能提供同意聲明和登入時刻。
GoogleUser.reloadAuthResponse()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2 物件和相關方法：
gapi.auth2.AuthorizeConfig 物件		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.AuthorizeResponse 物件		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.AuthResponse 物件		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.authorize()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.ClientConfig()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.getAuthInstance()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.init()		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.OfflineAccessOptions 物件		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.SignInOptions 物件		，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.signin2 物件和相關方法：
gapi.signin2.render()		，即可逐一移除離線觀看清單內的影片；使用 HTML DOM 載入 g_id_signin 元素，或對 google.accounts.id.renderButton 發出 JS 呼叫，即可觸發使用者登入 Google 帳戶。

從 Google 登入遷移 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

驗證及授權

異動情形

登入遷移範例

程式庫和設定

找出受影響的程式碼並進行測試

HTML 和 JavaScript

舊做法

彈出式模式

重新導向模式

最終顯示的內容

新做法

彈出式模式

重新導向模式

最終顯示的內容

HTML 和 JavaScript API

從任何頁面使用 One Tap 登入

權杖回應

使用者同意聲明和撤銷權限

工作階段狀態和 Listener

Cookie

使用者登入功能的物件遷移參考資料

從 Google 登入遷移