Android 上的 Permissions API

如要使用任何 Android 適用的 Home API，應用程式必須具備存取使用者住家裝置的權限 (在 API 中稱為「結構」)。使用者可以透過 Permissions API，使用 Google 帳戶授權 Home API 應用程式存取家中裝置。

使用者可透過權限流程建立結構 (如果尚未設定)，不必使用 Google Home app (GHA)。

整合 Permissions API

繼續操作前，請務必先按照「在 Android 上初始化住家」一文的步驟操作。該步驟中的 homeManager 執行個體會用於此處的所有 Permissions 範例。

首先，請向 SDK 註冊 ActivityResultCaller。舉例來說，範例應用程式的處理方式如下：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

檢查權限

要求權限前，建議先檢查應用程式使用者是否已同意存取結構。如要這麼做，請呼叫 Home 執行個體的 hasPermissions() 方法，取得 Flow 的 PermissionsState 值：

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
          println("Permissions state unavailable, request permissions")

      PermissionsState.NOT_GRANTED ->
          println("OAuth permission is enabled but not granted yet, request permissions")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

如果檢查傳回 PermissionsState 或 NOT_GRANTEDPERMISSIONS_STATE_UNAVAILABLE，表示使用者或應用程式沒有結構的存取權。如果檢查傳回 PermissionsState，但後續對 structures() 的呼叫未傳回任何結構，則使用者可能已透過 GHA 設定頁面撤銷應用程式的存取權，或是使用者沒有必要的存取權。GRANTED

要求權限

您必須授予應用程式權限，才能存取特定住家結構體內的裝置。

如果使用者尚未授予權限，請使用 Home 執行個體的 requestPermissions() 方法啟動權限使用者介面，並處理結果：

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

如要順利啟動權限使用者介面，您必須先為應用程式設定 OAuth。

授予權限

現在您應該可以執行應用程式，並讓使用者授予權限。可授予權限的使用者類型，以及可授予權限的裝置類型，會因您是否已在 Google Home Developer Console 中註冊應用程式而異。

如要使用 Home API 發布應用程式，必須先Developer Console註冊。測試及使用 Home API 並非必要。

如果應用程式未在 Developer Console中註冊，就會處於「未驗證」狀態。建議您使用這個方法測試 Home API：

• 只有在 OAuth 控制台中註冊為測試使用者的使用者，才能授予應用程式權限。未經驗證的應用程式最多只能有 100 位測試使用者。

• 未經驗證的應用程式可以存取 OAuth 支援的任何裝置類型 (裝置類型清單請見 Developer Console)。系統會授予存取結構中所有裝置的權限。

如果應用程式已在Developer Console 中註冊，並獲准存取一或多種裝置類型，且已完成 OAuth 的品牌驗證，就會處於「已驗證」狀態。如要發布應用程式，必須先達到這個狀態：

• 測試使用者限制不再適用。任何使用者都可以授予應用程式權限。
• 使用者只能將權限授予 Developer Console 中核准的裝置類型。

OAuth 設定完成後，應用程式呼叫 requestPermissions() 時會觸發下列對話方塊：

1. 系統會提示使用者選取想使用的 Google 帳戶。
2. 系統會提示使用者選取要授予應用程式存取權的住家結構體。
   1. 如果應用程式未經驗證，則可使用 Home API 支援的所有裝置類型。
   2. 如果是已驗證的應用程式，使用者只能將權限授予 Developer Console 中核准的裝置類型。
   3. 如果應用程式有權管理敏感裝置類型，使用者可以限制個別裝置的存取權。舉例來說，如果使用者有三把鎖，只能授予其中一把鎖的存取權。

取得授權後，應用程式就能使用 Home API 讀取及控制結構中的裝置狀態。如果使用者未授予應用程式特定裝置類型或私密裝置的權限，應用程式就無法使用 Home API 存取、控制或自動化這類裝置。

變更權限

如要授予存取不同結構中裝置的權限，可以啟動帳戶挑選器，讓使用者挑選要切換的 Google 帳戶和結構。在此期間，系統會再次向使用者顯示同意畫面，即使使用者先前已同意也一樣。

只要再次呼叫 requestPermissions()，並將 forceLaunch 旗標設為 true 即可：

homeManager.requestPermissions(forceLaunch=true)

撤銷權限

使用者可以撤銷先前授予的存取權：

1. 透過 Google 我的帳戶頁面，依序點選「資料與隱私權」>「第三方應用程式和服務」。這會撤銷最初授予同意聲明時核發的 OAuth 權杖，並撤銷使用者在所有介面 (手機) 和結構體上使用的任何應用程式例項存取權。

   使用者可能會透過深層連結導向「第三方應用程式和服務」子頁面，網址架構如下：

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

2. 透過「GHA」>「設定」>「已連結的應用程式」頁面。 按一下 settings GHA，即可前往「設定」頁面。然後按一下「已連結的應用程式」圖塊，系統會將您帶往類似同意畫面。使用者可以在這個頁面移除應用程式的存取權，也可以變更應用程式可存取的裝置類型或特定敏感裝置。

「Ok Google」權限

okGoogle 指令是裝置層級的指令，可用於自動化結構中的任何裝置。不過，Home API 應用程式可能無法存取所有裝置。下表說明在這種情況下如何強制執行權限。

使用者撤銷完整權限時的指引

如果使用者撤銷完整權限，所有現有的自動化動作都會停止運作。此外，如果使用者撤銷特定裝置的存取權，與這些裝置相關聯的啟動條件、限制條件和動作就會停止運作。

每次啟動應用程式時，請務必檢查權限是否仍有效。如果已撤銷，請務必移除所有先前的資料，包括應用程式中快取的資料。�