應用程式翻轉 (適用於 Android)

導入 OAuth 2.0 後，您可以視需要設定以 OAuth 為基礎的App Flip，讓Android使用者能更快速地將驗證系統中的帳戶連結至 Google 帳戶。以下各節說明如何設計及實作 App Flip，以便在 Android 上整合 Cloud-to-cloud。

設計指南

本節說明應用程式切換帳戶連結同意畫面的設計規定和建議。Google 呼叫應用程式後，應用程式會向使用者顯示同意畫面。

需求條件

1. 您必須提供 Google 授權聲明，例如「連結後，Google 將有權控制您的裝置。」
2. 您必須告知使用者，他們的帳戶將連結至 Google，而非 Google Home 或 Google 助理等特定 Google 產品。
3. 您必須在同意畫面中加入明確的行動號召，並使用「同意並連結」字樣來表示連結動作。這是因為使用者必須瞭解連結帳戶時，需要與 Google 分享哪些資料。
4. 如果使用者選擇不連結，您必須提供返回、拒絕或取消的方法。取消動作請使用「取消」一詞。
5. 您必須實作這項工作流程：使用者點選「同意並連結」後，您必須顯示連結成功訊息，並自動將使用者重新導向至 Google Home 應用程式。使用者現在應該會在 Google Home 應用程式中看到連結的裝置。按一下「取消」後，請將使用者重新導向回 Google Home 應用程式。

建議

建議您採取下列做法：

1. 顯示《Google 隱私權政策》。在同意畫面中加入《Google 隱私權政策》連結。

2. 要分享的資料。請使用簡潔明瞭的用語，告知使用者 Google 需要哪些資料，以及原因。

3. 可取消連結。提供使用者取消連結的機制，例如平台帳戶設定的網址。或者，您也可以加入 Google 帳戶的連結，讓使用者管理已連結的帳戶。

4. 可變更使用者帳戶。建議使用者切換帳戶的方法。如果使用者通常有多個帳戶，這項功能就特別實用。

   • 如果使用者必須關閉同意畫面才能切換帳戶，請將可復原的錯誤傳送給 Google，讓使用者透過 OAuth 連結和隱含流程登入所需帳戶。

5. 加入您的標誌。在同意畫面上顯示公司標誌。 請按照樣式指南放置標誌。如要顯示 Google 標誌，請參閱「標誌和商標」一文。

設定以 OAuth 為基礎的App Flip

以下各節說明以 OAuth 為基礎的應用程式快速連結功能必要條件，以及如何在 Google Home Developer Console 中設定應用程式快速連結專案。

建立雲端對雲端整合，並設定 OAuth 2.0 伺服器

設定 App Flip 之前，您必須先完成下列事項：

• 設定 OAuth 2.0 伺服器。如要進一步瞭解如何設定 OAuth 伺服器，請參閱「導入 OAuth 2.0 伺服器」。
• 建立雲端對雲端整合。如要建立整合，請按照「建立雲端對雲端整合」一文的操作說明進行。

在開發人員控制台中設定應用程式快速連結

下一節將說明如何在開發人員控制台中設定應用程式快速連結。

1. 填寫「帳戶連結」下方的所有必填(*) 欄位。(如果系統不支援應用程式快速連結，則會改用一般 OAuth)。
2. 提供雲端執行要求網址。雲端執行網址用於處理智慧住宅意圖。勾選「Local fulfillment」。
3. 在「應用程式快速連結 (選用)」下方，勾選「Android 應用程式」。
4. 填寫下列欄位：
• 應用程式 ID：應用程式 ID 是您為應用程式設定的專屬 ID。
• 應用程式簽署。Android 應用程式必須先使用公用金鑰憑證「簽署」，才能安裝。如要瞭解如何取得應用程式簽署，請參閱「驗證用戶端」。
• 授權意圖。在這個欄位中，輸入指定意圖動作的字串。
5. 如要視需要設定用戶端，請在「Scopes(s) (optional)」下方新增範圍，然後按一下「Add scope」。
6. 如果用戶端需要，請選取「Have Google transmit Client ID and secret via HTTP basic auth header」(讓 Google 透過 HTTP 基本驗證標頭傳輸用戶端 ID 和密鑰)。

現在可以繼續進行下一節，在 Android 應用程式中實作 App Flip。

在原生應用程式中導入 App Flip

如要導入 App Flip，您必須修改應用程式中的使用者授權碼，才能接受 Google 的深層連結。

OAuth 應用程式快速連結 (App Flip) 會將 Android 應用程式插入 Google 帳戶連結流程。傳統帳戶連結流程需要使用者在瀏覽器中輸入憑證。使用應用程式快速連結功能，可讓使用者延後登入 Android 應用程式，以便您運用現有授權。如果使用者已登入應用程式，就不必重新輸入憑證來連結帳戶。您只需要稍微修改程式碼，就能在 Android 應用程式中導入應用程式快速連結。

本文將說明如何修改 Android 應用程式，以支援應用程式快速連結。

試用範例

應用程式快速連結範例應用程式示範了 Android 上與應用程式快速連結相容的帳戶連結整合。您可以使用這個應用程式，驗證如何回應 Google 行動應用程式傳入的應用程式快速連結意圖。

範例應用程式已預先設定，可與 Android 版應用程式快速連結測試工具整合，您可以使用該工具驗證 Android 應用程式與應用程式快速連結的整合，然後再設定與 Google 的帳戶連結。這個應用程式會模擬啟用應用程式快速連結時，Google 行動應用程式觸發的意圖。

運作方式

如要整合應用程式快速連結，請按照下列步驟操作：

1. Google 應用程式會使用套件名稱，檢查裝置上是否已安裝您的應用程式。
2. Google 應用程式會使用套件簽章檢查，驗證安裝的應用程式是否正確。
3. Google 應用程式會建立意圖，在您的應用程式中啟動指定活動。這項意圖包含連結所需的額外資料。此外，系統也會透過 Android 架構解析這個意圖，檢查應用程式是否支援應用程式快速連結。
4. 應用程式會檢查套件簽章和提供的用戶端 ID，驗證要求是否來自 Google 應用程式。
5. 應用程式向 OAuth 2.0 伺服器要求授權碼。流程結束時，系統會將授權碼或錯誤傳回 Google 應用程式。
6. Google 應用程式會擷取結果，並繼續連結帳戶。如果提供授權碼，權杖交換會在伺服器之間進行，與瀏覽器型 OAuth 連結流程相同。

修改 Android 應用程式，支援應用程式快速連結

如要支援應用程式快速連結，請對 Android 應用程式進行下列程式碼變更：

1. 在 AndroidManifest.xml 檔案中新增 <intent-filter>，並加入與「應用程式快速連結意圖」欄位輸入值相符的動作字串。

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. 驗證呼叫端應用程式的簽章。

   您必須比對使用者可能用於帳戶連結的任何 Google 應用程式套件名稱和簽章。舉例來說，如要連結 Google Home 和 Google 搜尋應用程式，請新增其套件名稱和簽章：

   • Package name：com.google.android.apps.chromecast.app
   • 原始 SHA-256 歷來憑證： 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
   • 已輪替的 Play 應用程式簽署 SHA-256 憑證： 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

   和

   • Package name：com.google.android.googlequicksearchbox
   • 簽名： F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

   智慧住宅連結要求會直接由Google Home app (GHA)發出。如果應用程式會限制呼叫端，且先前僅允許 Google 搜尋應用程式，則必須將 com.google.android.apps.chromecast.app 及其 SHA-256 憑證加入許可清單，才能繼續使用應用程式快速連結功能。

   private fun verifyFingerprint(
       expectedPackage: String,
       expectedFingerprints: List<String>
   ): Boolean {
       val callingPackage = callingActivity?.packageName ?: return false
       if (callingPackage != expectedPackage) return false
       return expectedFingerprints.any { hex ->
           val sha256Bytes =
               hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
           packageManager.hasSigningCertificate(
               callingPackage,
               sha256Bytes,
               PackageManager.CERT_INPUT_SHA256
           )
       }
   }
   

3. 從意圖參數中擷取用戶端 ID，並確認用戶端 ID 與預期值相符。

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
   // Original lineage certificate (3D:7A...) and active rotated
   // Play App Signing certificate (5A:AD...)
   private val EXPECTED_FINGERPRINTS = listOf(
       "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
       "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
   )
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {
   
           // ...authorize the user...
       }
   }
   

4. 授權成功後，將產生的授權碼傳回 Google。

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. 如果發生錯誤，請改為傳回錯誤結果。

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

啟動意圖的內容

啟動應用程式的 Android 意圖包含下列欄位：

• CLIENT_ID (String)：在應用程式中註冊的 Google client_id。
• SCOPE (String[])：要求的範圍清單。
• REDIRECT_URI (String)：重新導向網址。

回應資料的內容

傳回 Google 應用程式的資料，是在應用程式中呼叫 setResult() 設定。這類資料包括：

• AUTHORIZATION_CODE (String)：授權碼值。
• resultCode (int)：傳達程序成功或失敗，並採用下列其中一個值：
  • Activity.RESULT_OK：表示成功，系統會傳回授權碼。
  • Activity.RESULT_CANCELLED：可復原的錯誤。表示使用者已取消程序。在這種情況下，Google 應用程式會使用您的授權網址，再次嘗試連結帳戶。
  • -2：表示發生錯誤。以下說明不同類型的錯誤。
• ERROR_TYPE (int)：錯誤類型，採用下列其中一個值：
  • 1：可復原的錯誤：Google 應用程式會嘗試使用授權網址連結帳戶。
  • 2：無法復原的錯誤：Google 應用程式會取消帳戶連結。
  • 3：要求參數無效或遺漏。
• ERROR_CODE (int)：代表錯誤性質的整數。如要瞭解各個錯誤代碼的意義，請參閱錯誤代碼表。

• ERROR_DESCRIPTION (String，選用)：說明錯誤的人類可讀狀態訊息。

resultCode == Activity.RESULT_OK 時，應提供 AUTHORIZATION_CODE 的值。在所有其他情況下，AUTHORIZATION_CODE 的值必須為空白。如果 resultCode == -2，則應填入 ERROR_TYPE 值。

錯誤代碼表

下表列出各種錯誤代碼，以及是否為可復原或無法復原的錯誤：

錯誤代碼	意義	可復原	無法復原
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

對於所有錯誤代碼，您必須透過 setResult 傳回錯誤結果，確保觸發適當的備用廣告。

在裝置上測試「App Flip」

您已建立雲端對雲端整合，並在控制台和應用程式中設定應用程式快速連結，現在可以在行動裝置上測試應用程式快速連結。您可以使用 Google Home 應用程式測試應用程式快速連結。

如要從 Google Home 應用程式測試 App Flip，請按照下列步驟操作：

1. 前往 Developer Console 並選取專案。
2. 依序前往「Cloud-to-cloud」>「測試」。
3. 從 Google Home 應用程式觸發帳戶連結流程：
1. 開啟 Google Home app (GHA)。
2. 按一下「+」按鈕。
3. 按一下「設定裝置」。
4. 按一下「是否有已經設定好的裝置？」
5. 從供應商清單中選取雲端對雲端整合。清單中的名稱會加上「[測試]」前置字元。從清單中選取 [測試] 整合項目後，系統應會開啟應用程式。
6. 確認應用程式已啟動，並開始測試授權流程。