Android の Permissions API

Android 用の Home API を使用する前に、アプリはユーザーの家にあるデバイス（API では「構造」と呼びます）にアクセスする権限を持っている必要があります。Permissions API を使用すると、ユーザーは Google アカウントを使用して、Home API アプリに家にあるデバイスへのアクセス権を付与できます。

権限フローを使用すると、ユーザーは Google Home app (GHA) を使用しなくても、まだ設定されていない構造を作成できます。

Permissions API を統合する

続行する前に、Android でホームを初期化するの手順を完了していることを確認してください。このステップの homeManager インスタンスは、ここにあるすべての権限の例で使用されています。

まず、SDK に ActivityResultCaller を登録します。たとえば、サンプルアプリでは次のように処理します。

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

権限を確認する

権限をリクエストする前に、アプリのユーザーが構造へのアクセスにすでに同意しているかどうかを確認することをおすすめします。そのためには、Home インスタンスの hasPermissions() メソッドを呼び出して、PermissionsState 値の Flow を取得します。

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_GRANTED または PERMISSIONS_STATE_UNAVAILABLE の場合、ユーザーまたはアプリのいずれかが構造体へのアクセス権を持っていないことを意味します。チェックで GRANTED の PermissionsState が返されたものの、その後の structures() の呼び出しで構造が返されなかった場合、ユーザーが GHA 設定ページからアプリへのアクセスを取り消したか、ユーザーに必要なアクセス権がないかのいずれかです。

権限をリクエストする

特定のストラクチャ内のストラクチャとデバイスにアクセスするには、アプリに権限を付与する必要があります。

ユーザーがまだ権限を付与していない場合は、Home インスタンスの requestPermissions() メソッドを使用して権限 UI を起動し、結果を処理します。

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}")
      }
    }
  }
}

権限 UI を適切に起動するには、アプリの OAuth を設定しておく必要があります。

権限を付与する

これで、アプリを実行してユーザーに権限を付与してもらうことができるはずです。権限を付与できるユーザーのタイプと、権限を付与できるデバイスのタイプは、アプリを Google Home Developer Console に登録しているかどうかによって異なります。

Home API を使用してアプリを公開するには、Developer Console 登録が必要です。Home API のテストと使用に必要ありません。

アプリが Developer Console に登録されていない場合、アプリは未確認の状態になります。これは、Home API の使用をテストする場合におすすめします。

• アプリの権限を付与できるのは、OAuth コンソールでテストユーザーとして登録されているユーザーのみです。未確認のアプリのテストユーザーは 100 人までです。

• 未確認アプリは、Home APIs の OAuth でサポートされているデバイスタイプ（Developer Console のデバイスタイプのリスト）のデバイスにアクセスできます。ストラクチャ内のすべてのデバイスにアクセス権が付与されます。

アプリが Developer Console に登録され、1 つ以上のデバイスタイプへのアクセスが承認され、OAuth のブランド確認が完了している場合、アプリは確認済みの状態になります。アプリを本番環境にリリースするには、この状態が必要です。

• テストユーザーの制限が適用されなくなります。どのユーザーもアプリに権限を付与できます。
• ユーザーは、Developer Console で承認されたデバイスタイプにのみ権限を付与できます。

OAuth が設定されたので、アプリから requestPermissions() への呼び出しによって次のダイアログがトリガーされます。

1. 使用する Google アカウントを選択するよう求めるメッセージが表示されます。
2. アプリにアクセスを許可するストラクチャを選択するよう求めるメッセージが表示されます。
   1. 未確認のアプリの場合、Home API でサポートされているすべてのデバイスタイプをアプリで使用できます。
   2. 確認済みのアプリの場合、ユーザーは Developer Console で承認されたデバイスタイプにのみ権限を付与できます。
   3. アプリが管理できる機密性の高いデバイスタイプについては、ユーザーはデバイスごとにアクセスを制限できます。たとえば、ユーザーが 3 つのロックを持っている場合、アクセス権を付与できるのはそのうちの 1 つのロックのみです。

権限が付与されると、アプリは Home API を使用して、ストラクチャ内のデバイスの状態を読み取り、制御できるようになります。特定のデバイスタイプまたは機密性の高いデバイスについて、ユーザーがアプリに権限を付与しない場合、アプリは Home API を使用してそのデバイスにアクセスしたり、操作したり、自動化したりすることはできません。

権限を変更

別のストラクチャ内のデバイスへのアクセス権を付与するには、アカウント選択ツールを起動して、切り替え先の Google アカウントとストラクチャをユーザーが選択できるようにします。このプロセスでは、以前に同意していた場合でも、同意画面が再度表示されます。

これを行うには、forceLaunch フラグを true に設定して requestPermissions() を再度呼び出します。

homeManager.requestPermissions(forceLaunch=true)

構造ヒントを使用して権限を変更する

構造ヒントを使用すると、ユーザーの Home API 権限の増分変更をリクエストする際に、アプリで特定の構造を事前に選択したり、利用可能な構造のリストを制限したりできます。構造パラメータを承認リクエストに渡すことで、権限ダイアログが選択された構造に自動的にフォーカスされるため、ユーザーの負担が軽減され、構成エラーを防ぐことができます。

構造ヒントは ConsentScreenOptions データクラスを使用して管理されます。ConsentScreenOptions クラスは、次の構成パラメータを受け入れます。

• structureId - 権限ダイアログで事前に選択する特定の構造 ID。更新される構造の構造プロパティを確認して取得します。
• allowedStructureIds - 構造 ID のリスト。指定すると、権限ダイアログで利用可能な構造がフィルタされ、このリストに含まれる構造のみが表示されます。ユーザーがすでに付与されている構造のリスト内に留まるようにする場合を除き、ほとんどの場合、指定しなくてもかまいません。
• allowStructureChange - ユーザーが事前選択された構造を変更できるかどうかを決定します。ユーザーの自然な動作をサポートするために、ほとんどの場合、allowedStructureIds と structureId の少なくとも 1 つが指定されている場合は、これを true に設定します。

このオブジェクトを requestPermissions() 呼び出しの省略可能なパラメータとして渡します。forceLaunch フラグは true に設定します。

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forceLaunch=true, consentOptions)

ユーザーには、ConsentScreenOptions オブジェクトで指定された構造にすでにフィルタされている同意画面が表示されます。

構造のヒントを使用してユーザーが構造を切り替えられるようにする

アプリに複数のストラクチャがあり、利用可能なストラクチャを切り替えられるようにしながら、1 つのストラクチャを事前に選択したい場合は、allowStructureChange フラグでストラクチャの変更を有効にし、allowedStructureIds でストラクチャのリストを指定します。

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

権限を取り消す

ユーザーは、以前に付与したアクセス権を取り消すことができます。

1. Google のマイアカウント ページ > [データとプライバシー] > [サードパーティ製のアプリとサービス] からアクセスできます。これにより、初回同意時に発行された OAuth トークンが取り消され、ユーザーがすべてのサーフェス（スマートフォン）と構造で使用していたアプリのすべてのインスタンスへのアクセスが取り消されます。

   ユーザーは、次の URL スキームを使用して、サードパーティ製のアプリとサービスのサブページにディープリンクで誘導されることがあります。

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

2. GHA > [設定] > [リンクされたアプリ] ページから。GHA の settings をクリックすると、[設定] ページに移動します。そこから、[リンクされたアプリ] タイルをクリックすると、同意画面に似たページに移動します。このページから、アプリへのアクセスを削除できます。また、このページで、アプリがアクセスできるデバイスの種類や特定の機密性の高いデバイスを変更することもできます。

ユーザーが権限を付与したデバイスタイプを表示する

Google Home エコシステムでは、ほとんどのデバイスタイプで、ユーザーは同じタイプのすべてのデバイスに対して一度に権限を付与できます。ロック、カメラ、ドアホンなどの機密性の高いデバイスタイプや制限付きのデバイスタイプについては、ユーザーは個別に権限を付与する必要があります。

機密性の高いデバイスタイプまたは制限付きのデバイスタイプにアクセスする権限がユーザーに付与されているかどうかを確認するには、構造レベルの consentedDeviceTypes() 関数を使用します。

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

OkGoogle の権限

okGoogle コマンドはデバイスレベルのコマンドであり、構造内の任意のデバイスを自動化するために使用できます。ただし、Home APIs アプリはすべてのデバイスにアクセスできるとは限りません。次の表に、このような場合に権限がどのように適用されるかを示します。

ユーザーがすべての権限を取り消した場合のガイダンス

ユーザーがすべての権限を取り消すと、既存の自動化はすべて機能しなくなります。また、ユーザーが特定のデバイスへのアクセスを取り消すと、それらのデバイスに関連付けられているスターター、条件、アクションは動作しなくなります。

アプリが起動するたびに、権限が有効であることを確認してください。権限が取り消された場合は、アプリケーションにキャッシュ保存されたデータを含め、以前のすべてのデータが削除されていることを確認してください。