API permissions

Avant d'utiliser l'une des API Home, 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, autoriser les applications des API Home à accéder aux appareils de sa maison.

Intégrer l'API Permissions

Avant de continuer, assurez-vous d'avoir suivi la procédure Initialiser la maison. L'instance homeManager de cette étape est utilisée dans tous les exemples d'autorisations présentés ici.

Commencez par enregistrer un ActivityResultCaller avec le SDK. Par exemple, voici comment l'application 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 ce faire, appelez la méthode hasPermissions() de l'instance Home pour obtenir un Flow de valeurs PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      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")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Si la vérification renvoie une PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, vous devez demander des autorisations. 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 Google Home app (GHA). Vous devez alors demander des autorisations. Sinon, l'utilisateur devrait déjà y avoir accès.

Demander des autorisations

Votre application doit être autorisée à 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 demander à un utilisateur d'accorder des autorisations. Le type d'utilisateurs pouvant accorder une autorisation et les types d'appareils pour lesquels des autorisations peuvent être accordées varient selon que vous avez enregistré votre application dans le Google Home Developer Console.

L'enregistrement Developer Console est obligatoire pour publier une application à l'aide des 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 Developer Console, elle est non validée. Nous vous recommandons d'utiliser cette méthode 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. Le nombre d'utilisateurs test est limité à 100 pour une application non validée.

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

Si une application est enregistrée dans le 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 est dans un état validé. Cet état est requis pour lancer une application en production:

• Les limites d'utilisateurs de test ne s'appliquent plus. Tout utilisateur peut accorder une 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.
   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 peut gérer, l'utilisateur peut limiter l'accès par appareil. Par exemple, si un utilisateur possède trois serrures, il ne peut accorder l'accès qu'à l'une d'entre 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 ou un appareil sensible particulier, 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 à laquelle passer. Au cours de ce processus, l'utilisateur verra à nouveau l'écran de consentement, 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 des 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. Le jeton OAuth émis lors de l'autorisation initiale sera révoqué, et l'accès à toute instance de l'application utilisée par l'utilisateur sur toutes les surfaces (téléphones) et structures sera révoqué.

2. Sur la page GHA > Paramètres > Applications associées. Cliquez sur settings dans GHA pour accéder à la page Settings (Paramètres). Cliquez ensuite sur la carte Applications associées, qui vous redirigera vers une page semblable à l'écran de consentement. Sur cette page, l'utilisateur peut supprimer l'accès à l'application. Il peut également utiliser cette même page pour modifier les types d'appareils ou les appareils sensibles spécifiques auxquels l'application peut accéder.

3. Sur la page Applications associées directement sur le Web.

Autorisations Ok Google

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