API Permissions sur Android

Avant d'utiliser l'une des API Home pour Android, l'application doit être autorisée à accéder aux appareils de la maison de l'utilisateur, appelés structure dans l'API. Avec l'API Permissions, l'utilisateur peut, à l'aide de son compte Google, accorder aux applications API Home l'accès aux appareils de sa maison.

Le flux d'autorisations permet à l'utilisateur de créer une structure si elle n'a pas déjà été configurée, sans avoir à utiliser Google Home app (GHA).

Intégrer l'API Permissions

Avant de continuer, assurez-vous d'avoir suivi la procédure Initialiser la maison sur Android. L'instance homeManager de cette étape est utilisée dans tous les exemples d'autorisations ci-dessous.

Commencez par enregistrer un ActivityResultCaller auprès du SDK. Voici par exemple comment l'exemple d'application gère cette opération :

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

Vérifier les autorisations

Avant de demander des autorisations, nous vous recommandons de vérifier si l'utilisateur de l'application a déjà donné son consentement pour accéder à la structure. Pour ce faire, appelez la hasPermissions() méthode de l'instance Home afin d'obtenir un Flow de PermissionsState valeurs :

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

Si la vérification renvoie un PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, cela signifie que l'utilisateur ou l'application n'a pas accès à la structure. Si la vérification renvoie un PermissionsState de GRANTED mais qu'un appel ultérieur à structures() ne renvoie aucune structure, cela signifie que l'utilisateur a révoqué l'accès à l'application via la page des paramètres GHA ou qu'il ne dispose pas de l'accès requis.

Demander des autorisations

Vous devez accorder une autorisation à votre application pour accéder aux structures et aux appareils d'une structure donnée.

Si l'utilisateur n'a pas encore accordé d'autorisations, utilisez la requestPermissions() méthode de l'instance Home pour lancer l'interface utilisateur des autorisations et traiter le résultat :

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

Pour que l'interface utilisateur des autorisations se lance correctement, vous devez déjà avoir configuré OAuth pour votre application.

Accorder des autorisations

Vous devriez maintenant pouvoir exécuter votre application et demander à un utilisateur d'accorder des autorisations. Le type d'utilisateurs pouvant accorder des autorisations et les types d'appareils pour lesquels des autorisations peuvent être accordées varient selon que vous avez enregistré votre application dans la Google Home Developer Console.

Developer Console l'enregistrement est obligatoire pour publier une application à l'aide de s API Home. Il n'est pas nécessaire de tester et d'utiliser les API Home.

Si une application n'est pas enregistrée dans la Developer Console, elle sera dans un état non vérifié. Nous vous recommandons cette option pour tester l'utilisation des API Home :

• Seuls les utilisateurs enregistrés en tant qu'utilisateurs test dans la console OAuth peuvent accorder des autorisations pour l'application. Une application non vérifiée est limitée à 100 utilisateurs test.

• Une application non vérifiée aura accès aux appareils de tous les types d'appareils compatibles avec OAuth pour les API Home (liste des types d'appareils dans la Developer Console). Tous les appareils d'une structure seront autorisés.

Si une application est enregistrée dans la Developer Console et qu'elle a été approuvée pour accéder à un ou plusieurs types d'appareils, et que la validation de la marque a été effectuée pour OAuth, elle sera dans un état vérifié. Cet état est requis pour lancer une application en production :

• Les limites d'utilisateurs test ne s'appliquent plus. Tout utilisateur peut accorder une autorisation à l'application.
• L'utilisateur ne peut accorder une autorisation qu'aux types d'appareils approuvés dans la Developer Console.

Maintenant qu'OAuth est configuré, l'appel de l'application à requestPermissions() déclenche les boîtes de dialogue suivantes :

1. L'utilisateur est invité à sélectionner le compte Google qu'il souhaite utiliser.
2. L'utilisateur est invité à sélectionner la structure à laquelle il souhaite accorder l'accès à l'application.
   1. Pour une application non vérifiée, tous les types d'appareils compatibles avec les API Home sont disponibles pour l'application.
   2. Pour une application vérifiée, l'utilisateur ne peut accorder une autorisation qu'aux types d'appareils approuvés dans Developer Console.
   3. Pour les types d'appareils sensibles que l'application est autorisée à gérer, l'utilisateur peut limiter l'accès appareil par appareil. Par exemple, si un utilisateur possède trois serrures, il ne peut accorder l'accès qu'à l'une d'elles.

Une fois l'autorisation accordée, l'application peut utiliser les API Home pour lire l'état des appareils de la structure et les contrôler. Si l'utilisateur n'accorde pas d'autorisation à l'application pour un type d'appareil particulier ou un appareil sensible, l'application ne pourra pas utiliser les API Home pour y accéder, le contrôler ou l'automatiser.

Modifier les autorisations

Pour accorder une autorisation d'accès aux appareils d'une autre structure, le sélecteur de compte peut être lancé pour permettre à l'utilisateur de choisir le compte Google et la structure à utiliser. Au cours de ce processus, l'écran de consentement s'affiche à nouveau, même si le consentement a déjà été accordé.

Pour ce faire, appelez à nouveau requestPermissions() avec l'indicateur forceLaunch défini sur true :

homeManager.requestPermissions(forceLaunch=true)

Révoquer les autorisations

Les utilisateurs peuvent révoquer l'accès précédemment accordé :

1. Sur la page Mon compte Google > Données et confidentialité > Applis et services tiers. Cela révoque le jeton OAuth émis lors de l'accord initial du consentement et l'accès à toute instance de l'application que l'utilisateur utilisait sur toutes les surfaces (téléphones) et structures.

   L'utilisateur peut être redirigé vers la sous-page Applis et services tiers à l'aide d'un lien profond utilisant le schéma d'URL suivant :

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

2. Sur la page GHA > Paramètres > Applis associées. Cliquez sur settings dans GHA pour accéder à la page Paramètres. Cliquez ensuite sur la tuile Applis associées pour accéder à une page semblable à l'écran de consentement. Sur cette page, l'utilisateur peut supprimer l'accès à l'application. Il peut également l'utiliser pour modifier les types d'appareils ou les appareils sensibles spécifiques accessibles à l'application.

Afficher les types d'appareils pour lesquels un utilisateur a accordé des autorisations

Dans l'écosystème Google Home, pour la plupart des types d'appareils, les utilisateurs peuvent accorder des autorisations pour tous les appareils de ce type à la fois. Pour les types d'appareils sensibles ou soumis à des restrictions, tels que les serrures, les caméras ou les sonnettes, les utilisateurs doivent accorder une autorisation pour chacun d'eux.

Pour déterminer si un utilisateur a accordé une autorisation d'accès à un type d'appareil sensible ou soumis à des restrictions, utilisez la fonction consentedDeviceTypes() au niveau de la structure :

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

Autorisations Ok Google

La okGoogle commande est une commande au niveau de l'appareil qui peut être utilisée pour automatiser n'importe quel appareil de la structure. Toutefois, une application API Home peut ne pas avoir accès à tous les appareils. Le tableau suivant décrit comment les autorisations sont appliquées dans de tels cas.

Conseils si l'utilisateur révoque toutes les autorisations

Si l'utilisateur révoque toutes les autorisations, toutes les automatisations existantes cesseront de fonctionner. De même, si l'utilisateur révoque l'accès à des appareils spécifiques, les déclencheurs, les conditions et les actions associés à ces appareils cesseront de fonctionner.

Chaque fois que l'application démarre, assurez-vous que les autorisations sont toujours en vigueur. Si elles ont été révoquées, assurez-vous que toutes les données précédentes sont supprimées, y compris celles mises en cache dans l'application.