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ée structure dans l'API. Grâce à 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.

Le flux d'autorisation permet à l'utilisateur de créer une structure et de lui attribuer une adresse postale si aucune n'a encore é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 présentés ici.

Commencez par enregistrer un ActivityResultCaller auprès du SDK. 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à accordé l'accès à 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 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

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'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'UI des autorisations se lance correctement, vous devez déjà avoir configuré OAuth pour votre application.

L'interface utilisateur de consentement des autorisations s'affiche dans les paramètres régionaux configurés avec HomeClient.setLocale(), ou par défaut dans les paramètres régionaux de l'application ou de l'appareil s'ils ne sont pas définis. Pour afficher l'écran de consentement dans une langue spécifique, appelez setLocale() sur votre instance HomeClient avant d'appeler requestPermissions(). Pour en savoir plus, consultez Configurer les paramètres régionaux de l'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 l'autorisation 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 ou non.

L'enregistrement Developer Console est requis pour publier une application à l'aide des API Home. Il n'est pas nécessaire pour tester et utiliser les API Home.

Si une application n'est pas enregistrée dans Developer Console, elle sera à l'état non validé. Cette option est recommandée 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 (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 sera à l'é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 l'autorisation à l'application.
• L'utilisateur ne peut accorder l'autorisation que pour les 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 appareil par appareil. Par exemple, si un utilisateur possède trois serrures, il peut n'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 l'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 d'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'écran de consentement s'affiche à nouveau, même si l'utilisateur l'a déjà accepté.

Pour ce faire, appelez à nouveau requestPermissions() avec forcePermissionFlow défini sur ForcePermissionFlow.FORCE_LAUNCH :

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Modifier les autorisations avec la pré-sélection de structure

La pré-sélection de structure permet à une application de pré-sélectionner une structure spécifique ou de limiter la liste des structures disponibles lorsqu'elle demande une modification incrémentielle des autorisations des API Home de l'utilisateur. En transmettant les paramètres de structure dans la demande d'autorisation, la boîte de dialogue d'autorisation se concentre automatiquement sur la structure choisie, ce qui réduit les frictions pour l'utilisateur et évite les erreurs de configuration.

La pré-sélection de structure est gérée à l'aide de la classe de données ConsentScreenOptions. La classe ConsentScreenOptions accepte les paramètres de configuration suivants :

• structureId : ID de la structure spécifique à présélectionner dans la boîte de dialogue d'autorisation. Pour l'obtenir, vérifiez les propriétés de la structure pour la structure en cours de mise à jour.
• allowedStructureIds : liste d'ID de structures. Si elle est fournie, la boîte de dialogue d'autorisation filtre les structures disponibles pour n'afficher que celles de cette liste. Dans la plupart des cas, vous pouvez laisser ce champ vide, sauf si vous souhaitez vous assurer que l'utilisateur reste dans une liste de structures déjà accordées.
• allowStructureChange : détermine si l'utilisateur est autorisé à modifier la structure présélectionnée. Définissez cette option sur true si au moins l'un des éléments allowedStructureIds et structureId est spécifié dans la plupart des cas pour assurer un comportement naturel pour l'utilisateur.

Transmettez cet objet en tant que paramètre facultatif dans l'appel requestPermissions(), avec forcePermissionFlow défini sur ForcePermissionFlow.FORCE_LAUNCH :

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(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

L'utilisateur verra l'écran de consentement déjà filtré pour la structure indiquée dans l'objet ConsentScreenOptions.

Autoriser l'utilisateur à changer de structure avec la pré-sélection de structure

Si un utilisateur dispose de plusieurs structures dans une application et que vous souhaitez en présélectionner une tout en lui permettant de basculer entre ses structures disponibles, activez les modifications de structure avec l'option allowStructureChange et fournissez une liste de structures dans allowedStructureIds :

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

Révoquer des autorisations

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

1. Dans les paramètres de votre compte Google > Données et confidentialité > Applis et services tiers. Cela révoquera le jeton OAuth émis lors de l'autorisation initiale, ainsi que l'accès à toutes les instances de l'application que l'utilisateur utilisait sur l'ensemble des surfaces (téléphones) et des structures.

   L'utilisateur peut être redirigé vers la sous-page Applications 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. Via 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 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 auxquels l'application peut accéder.

Suppression et exportation des données utilisateur

La plate-forme gère automatiquement la suppression des données du backend lorsqu'un utilisateur supprime son compte Google ou quitte une structure :

• Si l'utilisateur supprimé est le seul propriétaire d'une structure, la plate-forme supprime la structure et ses associations d'appareils.
• Si d'autres propriétaires restent dans une structure partagée, la structure et ses appareils partagés sont conservés pour les membres restants. La plate-forme supprime l'adhésion de l'utilisateur qui est parti et dissocie tous les appareils Cloud-to-cloud tiers connectés uniquement via les identifiants de cet utilisateur.
• La suppression du compte entraîne la suppression immédiate et définitive des données de structure et des autorisations d'application de l'utilisateur. Même si l'utilisateur récupère ultérieurement son compte Google, ses structures et ses autorisations ne sont pas restaurées.

Les API Home ne fournissent pas de points de terminaison pour exporter ou supprimer les données du compte Google d'un utilisateur. Invitez les utilisateurs disposant d'un compte Google à accéder à Google Takeout pour exporter leurs données Google Home et aux paramètres de leur compte Google pour gérer la suppression de leur compte.

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 en même temps. Pour les types d'appareils sensibles ou restreints, tels que les serrures, les caméras ou les sonnettes, les utilisateurs doivent accorder l'autorisation individuellement.

Pour déterminer si un utilisateur a accordé l'autorisation d'accéder à un type d'appareil sensible ou restreint, 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
            }
        }
    }
}

OkGoogle permissions

La commande okGoogle 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 Home APIs 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 les autorisations complètes

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

Chaque fois que l'application démarre, vérifiez 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 les données mises en cache dans l'application.

Lorsque l'accès à la structure est révoqué, un événement StructureAccessRevokedEvent est envoyé à votre backend cloud. Consultez Structure grants (Autorisations de structure) pour connaître le workflow de révocation de bout en bout pour le cloud et l'application mobile du partenaire.