Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

從 Google 登入遷移

本指南說明如何進行必要變更及採取相關步驟，將 JavaScript 程式庫從舊版 Google 登入平台程式庫成功遷移至新版 Google Identity 服務程式庫，以進行驗證。

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

驗證及授權

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

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

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

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

如果您的用途包含授權，請參閱「使用者授權的運作方式」和「遷移至 Google Identity 服務，確保應用程式使用全新改良的 API。

異動情形

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

全新低摩擦的 One Tap 和自動登入流程，減少個別步驟，
更新後的登入按鈕，可提供個人化使用者體驗，
網頁上一致的品牌宣傳和統一的登入行為可提升理解和信任感，
快速存取內容；使用者可直接從網站上的任何位置註冊及登入，不必先前往登入或帳戶頁面。

對開發人員而言，我們的重點是簡化程序、提升安全性，並盡可能加快整合速度。部分改善項目包括：

您可以使用 HTML，將使用者登入選項新增至網站的靜態內容，
登入驗證與授權和使用者資料分享作業分開，因此不再需要複雜的 OAuth 2.0 整合，即可讓使用者登入網站，
系統仍支援彈出式視窗和重新導向模式，但 Google 的 OAuth 2.0 基礎架構現在會重新導向至後端伺服器的登入端點，
將先前的 Google Identity 和 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 類型為「網頁應用程式」，且
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 作業和參數名稱。新程式庫會將 ID 權杖發布至 credential 參數中的端點。最後，請在後端伺服器上驗證 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
彈出式視窗

使用者登入狀態不會將按鈕文字從「登入」更新為「已登入」。使用者同意後，或是在回訪時，個人化按鈕會顯示使用者的姓名、電子郵件地址和個人資料相片。

在這個僅限驗證的範例中，新的 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() 用法，並讓應用程式直接管理每個使用者工作階段的狀態和登入狀態。

工作階段狀態和接聽程式

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

Google 帳戶的登入狀態，以及應用程式的會期狀態和登入狀態是不同的概念。

使用者登入 Google 帳戶和應用程式的狀態彼此獨立，但使用者成功通過驗證並登入 Google 帳戶時除外。

如果網站包含「使用 Google 帳戶登入」、One Tap 或自動登入功能，使用者必須先登入 Google 帳戶，才能：

在首次註冊或登入網站時，同意分享使用者設定檔，
並在日後返回網站時用於登入。

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

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

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

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

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

Cookie

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

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

新的 Google Identity 服務程式庫可根據您的設定選項，選擇性設定下列跨網域 Cookie：

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

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

如果您管理多個網域或子網域，請參閱「在子網域中顯示一鍵登入」，進一步瞭解如何使用 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()	IdConfiguration.callback 適用於 JS 和 HTML data-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 元素，或 JS 呼叫 google.accounts.id.renderButton，都會觸發使用者登入 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 元素，或 JS 呼叫 google.accounts.id.renderButton，都會觸發使用者登入 Google 帳戶。

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

驗證及授權

異動情形

登入遷移範例

程式庫和設定

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

HTML 和 JavaScript

舊方法

彈出式視窗模式

重新導向模式

最終顯示的內容

新做法

彈出式視窗模式

重新導向模式

最終顯示的內容

HTML 和 JavaScript API

透過 One Tap 從任何頁面登入

權杖回應

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

工作階段狀態和接聽程式

Cookie

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

從 Google 登入遷移