從 Google 登入遷移

本指南可協助您瞭解必要的變更和步驟,以成功將 JavaScript 程式庫從先前的 Google 登入平台程式庫遷移至新版 Google Identity 服務程式庫,以進行驗證

如果您的用戶端使用適用於 JavaScript 的 Google API 用戶端程式庫或其他舊版程式庫進行授權,請參閱遷移至 Google Identity 服務以瞭解詳情。

驗證及授權

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

如同先前的 Google 登入平台程式庫,新的 Google Identity Services 程式庫能夠同時支援驗證和授權程序。

不過,新的程式庫會區隔這兩個程序,以降低開發人員將 Google 帳戶與應用程式整合的複雜度。

如果您的用途僅涉及驗證,請繼續閱讀這個頁面。

如果您的用途包括授權,請參閱「使用者授權的運作方式」和「遷移至 Google Identity 服務」一文,確保應用程式使用的是改良過的新版 API。

異動情形

針對使用者,新的 Google Identity Services 程式庫提供多項可用性改善。主要包含:

  • 新的一觸即通自動登入流程簡化了個別步驟
  • 包含使用者個人化功能的新版登入按鈕。
  • 在整個網路維持一致的品牌形象和一致的登入行為 提升使用者理解度和信任感
  • 迅速取得內容;使用者可以直接從網站的任何位置註冊及登入,不必先造訪登入或帳戶頁面。

對開發人員來說,我們的目標是降低複雜性、提高安全性,並盡可能加快整合速度。其中幾項改善包括:

  • 選擇僅使用 HTML 將使用者登入新增至網站的靜態內容
  • 區隔登入驗證與授權、使用者資料共用,不再需要經過 OAuth 2.0 整合的複雜性,讓使用者登入您的網站。
  • 系統仍支援彈出式視窗和重新導向模式,但 Google 的 OAuth 2.0 基礎架構現在會重新導向至後端伺服器的登入端點。
  • 將舊版 Google Identity 和 Google API JavaScript 程式庫的功能整合到單一新程式庫。
  • 對於登入回應,您現在可以決定是否要使用 Promise,以及是否要透過 getter 樣式函式間接移除。

登入遷移範例

如果您要從現有的 Google 登入按鈕進行遷移,而且只想讓使用者登入網站,最直接的方法就是更新為新的個人化按鈕。方法是切換 JavaScript 程式庫,並將程式碼集更新為使用新的登入物件。

程式庫與設定

舊版 Google 登入平台程式庫:apis.google.com/js/platform.jsJavaScript 適用的 Google API 用戶端程式庫gapi.client,都不再需要進行使用者驗證和授權。已由一個新的 Google Identity Services JavaScript 程式庫取代:accounts.google.com/gsi/client

前三個 JavaScript 模組:所有用於登入的 apiclientplatform 都是從 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>

最終顯示的內容

使用視覺屬性自訂「使用 Google 帳戶登入」按鈕大小、形狀、顏色。顯示 One Tap 彈出式視窗以及個人化按鈕,以改善登入率。

「使用 Google 帳戶登入」按鈕 輕觸一下
彈出式視窗

使用者登入狀態不會將按鈕文字從「登入」更新為「已登入」。提供同意聲明或回訪後,個人化按鈕會包含使用者的姓名、電子郵件地址和個人資料相片。

在本僅限驗證的範例中,新的 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 回呼處理常式的彈出式視窗,或
  • 在「Sign in With 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() 及其已註冊回呼處理常式的所有參照。

先前,事件監聽器是用來分享使用者 Google 帳戶的登入狀態變更。系統已不再支援事件監聽器。

移除 listen()auth2.currentUserauth2.isSignedIn 的任何參照。

餅乾

「使用 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=redirectdata-login_uri 設定 HTML API,或

    • 使用 ux_mode=redirectJavaScript 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() 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() ,即可逐一移除離線觀看清單內的影片;載入 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.getHostDomain() 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.authorized() ,即可逐一移除離線觀看清單內的影片;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() ,即可逐一移除離線觀看清單內的影片;載入 g_id_signin 元素或對 google.accounts.id.renderButton 的 JS 呼叫,會觸發使用者登入 Google 帳戶的程序。