Android 版 App Flip

實作 OAuth 2.0 後，您可以視需要設定 OAuth 式 App Flip，讓 Android 使用者能更快速地將驗證系統中的帳戶連結到他們的 Google 帳戶。以下章節將說明如何為 smart home 動作設計並實作 App Flip。

設計指南

本節說明 App Flip 帳戶連結同意畫面的設計需求和建議。Google 呼叫您的應用程式後，應用程式會向使用者顯示同意畫面。

需求條件

1. 您必須通知使用者的帳戶已連結到 Google，但「不是」連結至特定 Google 產品，例如 Google Home 或 Google 助理。

建議

建議您採取下列做法：

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

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

3. 加入明確的行動號召。在同意畫面中，加入明確的行動號召，例如「同意並連結」。這是因為使用者必須瞭解需要與 Google 分享哪些資料才能連結自己的帳戶。

4. 取消功能。如果使用者選擇不連結，可讓他們返回或取消取消訂閱。

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

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

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

7. 加入標誌。在同意畫面中顯示公司標誌。請按照樣式規範放置標誌。如要一併顯示 Google 的標誌，請參閱標誌和商標。

設定以 OAuth 為基礎的應用程式 Flip

以下各節說明以 OAuth 為基礎的應用程式翻轉必備條件，以及如何在 Actions 主控台設定應用程式翻轉專案。

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

設定應用程式切換前，您必須執行下列操作：

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

在 Actions 主控台設定應用程式翻轉

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

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

在 Android 應用程式中實作應用程式翻轉

如要導入 App Flip，您必須修改應用程式中的使用者授權碼，以便接受 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. 請確認您的應用程式已啟動，並開始測試授權流程。