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. Grâce à l'API Permissions, l'utilisateur peut, à l'aide de son compte Google, accorder aux applications Home APIs l'accès aux appareils de sa maison.

Intégrer l'API Permissions

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

Commencez par enregistrer un ActivityResultCaller avec le SDK. Par exemple, voici comment l'appli exemple gère cela :

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 méthode hasPermissions() de l'instance Home pour obtenir un Flow de valeurs 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())
    }
}

Si la vérification renvoie une valeur PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, cela signifie que l'utilisateur ou l'application n'ont pas accès à la structure. Si la vérification renvoie une valeur 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 sur la page des paramètres Google Home app (GHA) ou qu'il ne dispose pas de l'accès requis.

Demander des autorisations

Votre application doit obtenir l'autorisation d'accéder aux structures et aux appareils d'une structure donnée.

Si l'utilisateur n'a pas encore accordé d'autorisations, utilisez la méthode requestPermissions() de l'instance Home pour lancer l'UI 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'UI des autorisations se lance correctement, vous devez déjà avoir configuré OAuth pour votre application.

Octroyer des autorisations

Vous devriez maintenant pouvoir exécuter votre application et obtenir l'autorisation d'un utilisateur. Le type d'utilisateurs pouvant accorder l'autorisation et les types d'appareils disponibles pour accorder l'autorisation varient selon que vous avez enregistré votre application dans Google Home Developer Console.

L'enregistrement Developer Console est obligatoire pour publier une application à l'aide des API Home. Elle n'est pas obligatoire pour tester et utiliser les API Home.

Si une application n'est pas enregistrée dans Developer Console, elle sera dans l'état non validée. Nous vous recommandons de procéder comme suit pour tester l'utilisation des API Home :

• Seuls les utilisateurs enregistrés en tant qu'utilisateurs de test dans la console OAuth peuvent accorder des autorisations pour l'application. Le nombre d'utilisateurs de test est limité à 100 pour une application non validée.

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

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

• Les limites des utilisateurs de test ne s'appliquent plus. Tout utilisateur peut accorder l'autorisation à l'application.
• L'utilisateur ne peut accorder l'autorisation qu'aux types d'appareils approuvés dans le 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 validée, tous les types d'appareils compatibles avec les API Home sont disponibles pour l'application.
   2. Pour une application validée, l'utilisateur ne peut accorder l'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 restreindre l'accès pour chaque appareil. Par exemple, si un utilisateur dispose 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 l'autorisation à l'application pour un type d'appareil ou un appareil sensible spécifique, l'application ne pourra pas utiliser les API Home pour y accéder, le contrôler ou l'automatiser.

Modifier les autorisations

Pour accorder l'autorisation d'accéder aux appareils dans une autre structure, le sélecteur de compte peut être lancé pour permettre à l'utilisateur de choisir le compte Google et la structure vers lesquels basculer. Au cours de ce processus, l'utilisateur sera à nouveau invité à donner son consentement, même s'il l'a déjà fait.

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 Mes comptes Google > Données et confidentialité > Applications et services tiers. Cela révoquera le jeton OAuth émis lors de l'autorisation initiale 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é avec un lien profond vers la sous-page Applications et services tiers à l'aide du schéma d'URL suivant :

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

2. Sur la page GHA > Paramètres > Applications associées. Cliquez sur settings dans GHA pour accéder à la page Paramètres. Cliquez ensuite sur la tuile Applications associées, qui vous redirige vers 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 auxquels l'application peut accéder.

Autorisations "Ok Google"

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