Android 版 App Flip

實作 OAuth 2.0 之後，您可以視需要設定 OAuth 型 App Flip , which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action.

Design guidelines

This section describes the design requirements and recommendations for the App Flip account linking consent screen. After Google calls your app, your app displays the consent screen to the user.

Requirements

1. You must communicate that the user's account is being linked to Google, not to a specific Google product, such as Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google's Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as "Agree and link." This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

6. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

7. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

為 OAuth 型應用程式翻轉設定

以下各節說明使用 OAuth 應用程式 Flip 的先決條件，以及如何在 Actions 主控台設定 App Flip 專案。

建立智慧住宅動作並設定 OAuth 2.0 伺服器

設定應用程式轉換功能之前，您必須先完成下列事項：

• 設定 OAuth 2.0 伺服器。如要進一步瞭解如何設定 OAuth 伺服器，請參閱實作 OAuth 2.0 伺服器一文。
• 建立動作。如要建立動作，請按照建立動作專案中的說明操作。

在動作控制台中設定應用程式翻轉

以下章節說明如何在動作主控台中設定應用程式翻轉。

1. 填寫「OAuth 用戶端資訊」下方的所有欄位。 (如果不支援應用程式翻轉功能，系統將使用一般 OAuth 做為備用設定)。
2. 在「使用您的應用程式進行帳戶連結 (選用)」下方勾選 [啟用 Android 裝置]。
3. 填寫下列欄位：
• 申請 ID。應用程式 ID 是您為應用程式設定的唯一 ID。
• 應用程式簽名。Android 應用程式必須使用公用金鑰憑證「簽署」，才能加以安裝。如要瞭解如何取得應用程式簽名，請參閱驗證用戶端一文。
• 授權意圖。在這個欄位中，輸入用來指定意圖動作的字串。
4. 如果您想自行設定用戶端，請新增範圍，然後按一下「設定用戶端 (選用)」底下的 [新增範圍]。
5. 按一下「儲存」。

在 Android 應用程式中導入應用程式翻轉功能

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

以 OAuth 為基礎的應用程式翻轉連結 (應用程式翻轉) 會將您的 Android 應用程式插入 Google 帳戶連結流程中。傳統的帳戶連結流程會要求使用者在瀏覽器中輸入憑證。使用 App Flip 延後使用者登入 Android 應用程式後，您就能利用現有的授權。如果使用者登入了您的應用程式，就不需要重新輸入憑證來連結自己的帳戶。您幾乎不需要修改程式碼，就能在 Android 應用程式中導入應用程式轉換功能。

在這份文件中，您將瞭解如何修改 Android 應用程式，以支援應用程式翻轉功能。

試閱

「應用程式翻轉」連結範例應用程式示範了與 Android 應用程式相容的回溯應用程式連結功能。您可以使用這個應用程式，驗證如何回應來自 Google 行動應用程式的 App Flip 意圖。

這個範例應用程式已預先設定為與 Android 應用程式轉換測試工具整合，讓您在設定與 Google 帳戶連結前，可用來驗證 Android 應用程式與 App Flip 的整合。這個應用程式會在啟用 App Flip 時模擬 Google 行動應用程式觸發的意圖。

運作方式

如要執行應用程式轉換整合，必須完成以下步驟：

1. Google 應用程式會使用套件名稱檢查裝置是否已安裝該應用程式。
2. Google app 會使用套件簽名檢查，驗證已安裝的應用程式是否正確。
3. Google 應用程式會建立一個意圖，以便在應用程式中啟動指定活動。此意圖包括連結所需的其他資料。也會透過 Android 架構解析這個意圖，檢查應用程式是否支援應用程式翻轉。
4. 應用程式會驗證要求是否來自 Google 應用程式。為執行此操作，應用程式會檢查套件簽名和提供的用戶端 ID。
5. 您的應用程式向 OAuth 2.0 伺服器要求授權碼。完成這個流程後，應用程式會傳回授權碼或 Google 應用程式錯誤。
6. Google 應用程式會擷取結果，並繼續連結帳戶。如果提供授權碼，則權杖交換作業會在伺服器對伺服器進行，就像在瀏覽器透過 OAuth 連結流程中一樣。

修改 Android 應用程式以支援應用程式翻轉

如要支援應用程式翻轉功能，請對 Android 應用程式變更以下程式碼：

1. 將 <intent-filter> 新增至 AndroidManifest.xml 檔案中，動作字串與您在「應用程式翻轉意圖」欄位中輸入的值相符。

   <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. 驗證通話應用程式的簽名。

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

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

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...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)：重新導向網址。

回應資料的內容

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

• AUTHORIZATION_CODE (String)：授權碼值。
• resultCode (int)：傳達程序是否成功，並採用下列其中一個值：
  • Activity.RESULT_OK：表示成功；會傳回授權碼。
  • Activity.RESULT_CANCELLED：代表使用者已取消程序。在這種情況下，Google 應用程式會嘗試使用您的授權網址進行帳戶連結。
  • -2：表示發生錯誤。不同類型的錯誤說明如下。
• ERROR_TYPE (int)：錯誤類型，可使用下列其中一個值：
  • 1：可復原錯誤：Google 應用程式會嘗試使用授權網址進行帳戶連結。
  • 2：無法復原的錯誤：Google app 已取消帳戶連結。
  • 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 傳回錯誤結果，以確保觸發適當的備用廣告。

在裝置上測試應用程式翻轉

您已經在主控台和應用程式中建立動作及應用程式翻轉功能，現在可以在行動裝置上測試應用程式轉換功能。您可以使用 Google 助理應用程式或 Google Home 應用程式測試應用程式翻轉功能。

如要從 Google 助理應用程式測試應用程式翻轉功能，請按照下列步驟操作：

1. 前往動作控制台，然後選取您的專案。
2. 按一下上方導覽列的 [測試]。
3. 透過 Google 助理應用程式觸發帳戶連結流程：
1. 開啟 Google 助理應用程式。
2. 按一下「設定」。
3. 在 [Google 助理] 分頁中按一下 [居家控制系統]。
4. 按一下 [新增(+)]。
5. 從供應商清單中選取你的動作。這會在清單中加上「[test]」前置字串。從清單中選取 [test] 動作時，系統應會開啟您的應用程式。
6. 確認應用程式已啟動，並開始測試您的授權流程。

如要透過 Google Home 應用程式測試應用程式翻轉功能，請按照下列步驟操作：

1. 前往動作控制台，然後選取您的專案。
2. 按一下上方導覽列的 [測試]。
3. 在 Google Home 應用程式中觸發帳戶連結流程：
1. 開啟 Google Home 應用程式 。
2. 按一下「+」按鈕。
3. 按一下 [設定裝置]。
4. 按一下「已經設定好了嗎？」。
5. 從服務供應商清單中選取智慧型住宅動作。這會在清單中加上「[test]」前置字串。從清單中選取 [test] 動作時，系統應會開啟您的應用程式。
6. 確認應用程式已啟動，並開始測試您的授權流程。