歡迎使用 Google Home 開發人員中心，探索全新功能，瞭解如何開發智慧住宅動作。注意：請繼續在「動作」控制台中建立動作。

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.

設計指南

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

需求條件

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

建議

建議您採取下列做法：

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

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

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

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

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

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

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

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

此圖顯示同意畫面範例，指出您在設計使用者同意畫面時，應遵循的各項個別規定和建議。
圖 1：帳戶連結同意畫面設計指南。

為 OAuth 型應用程式翻轉設定

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

建立智慧住宅動作並設定 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. 確認應用程式已啟動，並開始測試您的授權流程。
上一頁
建立 Actions 專案
下一頁
識別並同步處理