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.

Les API Home utilisent OAuth 2.0 pour accorder l'accès aux appareils de la structure. OAuth permet à un utilisateur d'accorder une autorisation à une application ou à un service sans avoir à divulguer ses identifiants de connexion. 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.

L'utilisation de l'API Permissions implique un certain nombre d'étapes dans votre application, Google Cloud et Google Home Developer Console:

1. Configurer OAuth dans Google Cloud
   1. Signer l'application
   2. Configurer l'écran de consentement OAuth
   3. Inscrire l'application et créer des identifiants
2. Intégrer l'API Permissions
   1. Vérifier les autorisations
   2. Demander des autorisations
3. Octroyer des autorisations
   1. Modifier les autorisations
   2. Révoquer des autorisations

Configurer OAuth dans Google Cloud

Si vous disposez déjà d'un client OAuth validé, vous pouvez l'utiliser sans en configurer un autre. Pour en savoir plus, consultez la section Si vous disposez d'un client OAuth existant.

Signer l'application

1. Générez une clé OAuth en exécutant l'application dans Android Studio. Lorsque vous exécutez ou déboguez une application dans Android Studio, une clé OAuth destinée au développement et au débogage est automatiquement générée. Pour une explication complète, consultez Android Studio: signer votre version de débogage.

   Connectez votre appareil mobile à votre ordinateur local. Android Studio affiche vos appareils connectés par numéro de modèle. Sélectionnez votre appareil dans la liste, puis cliquez sur Run project (Exécuter le projet). L'application exemple est ainsi créée et installée sur votre appareil mobile.

   Pour obtenir des instructions plus détaillées, consultez Exécuter des applications sur un appareil matériel sur le site des développeurs Android.

   Arrêtez maintenant l'application en cours d'exécution.

2. Obtenez l'empreinte SHA-1 du certificat OAuth en suivant les instructions détaillées dans la section Configurer OAuth 2.0 / Applications natives/Android sur le site d'aide de la console Google Cloud.

Configurer l'écran de consentement OAuth

1. Dans la console Google Cloud, accédez au tableau de bord du sélecteur de projet, puis sélectionnez le projet que vous souhaitez utiliser pour créer des identifiants OAuth.
2. Accédez à la page API et services, puis cliquez sur Identifiants dans le menu de navigation.

3. Si vous n'avez pas encore configuré votre écran de consentement pour ce projet Google Cloud, le bouton Configurer l'écran de consentement s'affiche. Dans ce cas, configurez votre écran d'autorisation en suivant la procédure ci-dessous. Sinon, passez à la section suivante.

   1. Cliquez sur Configurer l'écran d'autorisation. La page Écran de consentement OAuth s'affiche.
   2. Selon votre cas d'utilisation, sélectionnez Interne ou Externe, puis cliquez sur Créer. Le volet Écran de consentement OAuth s'affiche.
   3. Saisissez les informations sur la page d'informations sur l'application en suivant les instructions à l'écran, puis cliquez sur Enregistrer et continuer. Le volet Champs d'application s'affiche.
   4. Vous n'avez pas besoin d'ajouter de champs d'application. Cliquez donc sur Enregistrer et continuer. Le volet Utilisateurs de test s'affiche.
   5. Si vous souhaitez ajouter des utilisateurs pour tester l'accès à votre application, cliquez sur Ajouter des utilisateurs. Le volet Ajouter des utilisateurs s'affiche. Les utilisateurs tests ont le droit d'accorder des autorisations dans votre application.
   6. Dans le champ vide, ajoutez une ou plusieurs adresses e-mail de compte Google, puis cliquez sur Ajouter.
   7. Cliquez sur Enregistrer et continuer. Le volet Summary (Récapitulatif) s'affiche.
   8. Vérifiez les informations de votre écran de consentement OAuth, puis cliquez sur Retour au tableau de bord.

Pour en savoir plus, consultez la page d'aide de la Google Cloud Console Configurer votre écran de consentement OAuth.

Enregistrer l'application et créer des identifiants

Pour enregistrer l'application pour OAuth 2.0 et créer des identifiants OAuth, suivez les instructions fournies dans la section Configurer OAuth 2.0. Vous devez indiquer le type d'application, qui est application native/Android.

Ajoutez l'empreinte SHA-1 obtenue en signant l'application au client OAuth que vous avez configuré dans la console Google Cloud en suivant les instructions de la section Configurer OAuth 2.0 / Applications natives sur le site d'aide de la console Google Cloud.

Une fois votre appareil mobile connecté à votre ordinateur local, sélectionnez-le dans la liste, puis cliquez à nouveau sur Run project (Exécuter le projet) pour l'exécuter. Pour obtenir des instructions plus détaillées, consultez la section Exécuter des applications sur un appareil physique sur le site des développeurs Android.

Intégrer l'API Permissions

Les utilisateurs doivent accorder des autorisations à votre application pour accéder aux appareils d'une structure donnée. Pour commencer, assurez-vous d'avoir initialisé les API Home. 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'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 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. Pour accéder à la fonctionnalité d'enregistrement dans la console, contactez votre Technical Account Manager (TAM) Google.

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.

Si vous disposez déjà d'un client OAuth

Si vous disposez déjà d'un client OAuth validé pour une application publiée, vous pouvez utiliser votre client OAuth existant pour tester les API Home.

L'enregistrement Developer Console n'est pas obligatoire pour tester et utiliser les API Home. Toutefois, vous aurez toujours besoin d'un enregistrement Developer Console approuvé pour publier votre application, même si vous disposez d'un client OAuth validé à partir d'une autre intégration.

Les considérations suivantes s'appliquent :

• Une limite de 100 utilisateurs s'applique lorsque vous utilisez un client OAuth existant. Pour savoir comment ajouter des utilisateurs de test, consultez la section Configurer l'écran de consentement OAuth. Indépendamment de la validation OAuth, les API Home imposent une limite de 100 utilisateurs pouvant accorder des autorisations à votre application. Cette limitation est levée une fois l'enregistrement de Developer Console terminé.

• L'Developer Consoleenregistrement doit être envoyé pour approbation lorsque vous êtes prêt à restreindre les autorisations de type d'appareil via OAuth en vue de mettre à jour votre application avec les API Home.

Pour les applications Google Cloud dont la validation OAuth est toujours en attente, les utilisateurs ne peuvent pas terminer le flux OAuth tant que la validation n'est pas terminée. Les tentatives d'octroi d'autorisations échouent et renvoient l'erreur suivante:

Access blocked: <Project Name> has not completed the Google verification process.

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.