Initialiser la maison sur Android

Avant d'utiliser l'une des API Home pour Android, vous devez initialiser la maison dans votre application. Au cours de cette étape, vous allez créer une instance singleton de Home pour le contexte local.

Une seule instance de Home doit être active à la fois.

Il s'agit du point d'entrée des API Home. Vous devez également déclarer les caractéristiques et les types d'appareils que vous comptez utiliser avec les API Device &Structure et Automation. Si vous débutez avec l'écosystème Google Home et que vous ne savez pas quelles caractéristiques ou quels types d'appareils enregistrer, nous vous en suggérons quelques-uns des plus courants dans ce guide.

Créer une instance Home

Pour commencer, importez ces packages dans votre application :

import android.content.Context
import com.google.home.FactoryRegistry
import com.google.home.HomeConfig
import com.google.home.Home

Pour initialiser les API Home :

Obtenez une référence au Application contexte. Ce contexte ne dépend d'aucun cycle de vie d'activité et restera actif tant que votre application sera en cours d'exécution. Vous pouvez l'obtenir en appelant getApplicationContext() dans une Activity ou un Service :
```
val context = getApplicationContext()
```

Créez une FactoryRegistry instance avec toutes les caractéristiques et tous les types d'appareils que vous comptez utiliser dans votre application.

Dans ce guide, nous vous suggérons quelques caractéristiques et types d'appareils courants (types d'appareils Light, Plug, Sensor, Switch et Thermostat, caractéristiques de présence et de l'Assistant pour les automatisations) si vous ne savez pas ce dont vous avez besoin. Pour en savoir plus, consultez Enregistrement des caractéristiques et des types d'appareils.

val registry = FactoryRegistry(
  traits = listOf(
            AirQuality,
            AreaAttendanceState,
            AreaPresenceState,
            AssistantBroadcast,
            AssistantFulfillment,
            BooleanState,
            ColorControl,
            ExtendedColorControl,
            FlowMeasurement,
            IlluminanceMeasurement,
            LevelControl,
            Notification,
            OccupancySensing,
            OnOff,
            RelativeHumidityMeasurement,
            Switch,
            TemperatureMeasurement,
            Thermostat),
  types = listOf(
            AirQualitySensorDevice,
            ColorDimmerSwitchDevice,
            ColorTemperatureLightDevice,
            ContactSensorDevice,
            DimmableLightDevice,
            DimmablePlugInUnitDevice,
            DimmerSwitchDevice,
            ExtendedColorLightDevice,
            FlowSensorDevice,
            GenericSwitchDevice,
            HumiditySensorDevice,
            LightSensorDevice,
            OccupancySensorDevice,
            OnOffLightDevice,
            OnOffLightSwitchDevice,
            OnOffPluginUnitDevice,
            OnOffSensorDevice,
            SpeakerDevice,
            TemperatureSensorDevice,
            ThermostatDevice))

Les instructions d'importation pour chaque caractéristique et type d'appareil enregistrés ici sont obligatoires (Android Studio devrait vous inviter à les ajouter).

Instanciez un HomeConfig à l'aide du Dispatchers.IO contexte de coroutine et de votre instance de registre.

val homeConfig = HomeConfig(
        coroutineContext = Dispatchers.IO,
        factoryRegistry = registry)

Enfin, créez l'instance singleton de Home, qui est le point d'entrée des API, à l'aide du contexte et du HomeConfig.
```
val homeManager: HomeClient = Home.getClient(context, homeConfig)
```

Pour éviter les erreurs liées à des sessions non valides, il est important de ne créer qu'une seule instance singleton de Homeen l'encapsulant dans une déclaration d'objet.

Par exemple, l'application exemple procède comme suit :

internal object HomeClientModule {
  @Provides
  @Singleton
  fun provideHomeClient(@ApplicationContext context: Context): HomeClient {
    return Home.getClient(
      context,
      HomeConfig(
        coroutineContext = IODispatcherModule.provideIoDispatcher(),
        factoryRegistry = registry,
      ),
    )
  }
}

Connexion Google initiée par l'application

Vous pouvez gérer les authentifications Google de vos utilisateurs dans votre application. Cela vous permet d'utiliser le même compte utilisateur dans différents services Google tels que Google Home, Drive, Maps, etc.

Avec la connexion Google initiée par l'application, vous pouvez obtenir une instance HomeClient explicitement liée à un utilisateur spécifique, ce qui vous permet de contourner le sélecteur de compte Google et l'écran de consentement lorsque le compte est déjà autorisé.

De plus, cette approche empêche les utilisateurs de voir deux écrans de sélection de compte différents : l'un provenant de la connexion de l'application et l'autre de Google Home.

Pour ce faire, vous devez vous reporter à Authentifier les utilisateurs avec Se connecter avec Google et suivre les étapes suivantes :

Créer un ID client d'application Web OAuth

Ouvrez la console Google Cloud.
- Accédez à la page Identifiants de la console Google Cloud.
- Sélectionnez un projet existant ou créez-en un.
Configurez l'écran de consentement OAuth (si ce n'est pas déjà fait).
- Avant de créer des identifiants, assurez-vous que l'écran de consentement OAuth est configuré avec les informations de votre application, y compris les URL des règles de confidentialité et des conditions d'utilisation.
Créez un ID client OAuth (type d'application Web).
- Sur la page "Identifiants", cliquez sur + CREATE CREDENTIALS et sélectionnez ID client OAuth dans le menu déroulant.
- Pour le Type d'application, sélectionnez Application Web.
- Saisissez un nom pour votre client Web (par exemple, "Backend Web de mon application").
- Cliquez sur Créer.
Récupérez l'ID client.
- Une fois créé, l'ID client s'affiche dans la console. Il s'agit de la valeur que vous utiliserez dans votre application Android (par exemple, "{project number}-.....apps.googleusercontent.com")
- Nous vous recommandons de stocker l'ID client en externe (par exemple, dans build.gradle) plutôt que de le coder en dur directement.

Instancier une requête Google Sign-In

Utilisez l'ID de l'application Web pour créer une requête Google Sign-In :

// Your Google Cloud console Web Client ID for Google Sign-In
val serverClientId = BuildConfig.DEFAULT_WEB_CLIENT_ID

// Build the request for Google ID token
val googleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(false) // Show all Google Accounts on the device
    .setServerClientId(serverClientId) // embed WebClientID in token
    .build()

// Build the GetCredentialRequest
val request = GetCredentialRequest.Builder().addCredentialOption(googleIdOption).build()

Créer le flux Se connecter avec Google

Pour implémenter le flux de connexion, utilisez CredentialManager pour exécuter une requête Sign in with Google. Une fois que l'utilisateur a sélectionné un compte, extrayez son adresse e-mail du jeton d'ID Google obtenu pour créer un android.accounts.Account. Ce compte est ensuite utilisé pour initialiser une instance HomeClient spécifiquement liée à cet utilisateur connecté.

  try {
    // CredentialManager is responsible for interacting with various credential providers on the device
    val credentialManager = CredentialManager.create(context)
    // Credential returns when user has selected an account and the getCredential call completes
    val result = credentialManager.getCredential(context = context, request = request)
    val credential = result.credential

    if (
      credential is CustomCredential &&
      credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL
    ) {
      try {
        val googleCredential = GoogleIdTokenCredential.createFrom(credential.data)
        googleCredential.id.let { userEmail ->
          Log.i(TAG, "Email found in Google ID Token: $email")
          /*
           Why "com.google"?
           The string "com.google" is a standard identifier used in Android's android.accounts.
           Account system to represent accounts managed by Google. This is often used when
           interacting with Android's Account Manager or when using Google-specific APIs. So,
           even if the email ends in "@gmail.com", the underlying account type or provider is
           still considered "com.google" within the Android system.
          */
          val account = Account(userEmail, "com.google")
          Log.d(TAG,"Switched account to : $userEmail")
          // Get the new Home Client Instance with the userEmail
        }
        Log.i(TAG, "Account switch complete. Emitting navigation event.")
      } catch (e: Exception) {
        Log.e(TAG,"Could not convert CustomCredential to Google ID Token", e)
      }
    }
  } catch (e: Exception) {
    Log.e(TAG, "Google Sign-In failed with unexpected error", e)
  }

Obtenir une nouvelle instance HomeClient

Suivez les mêmes étapes que celles décrites dans Créer une instance Home, mais au lieu d'appeler Home.getClient(context, homeConfig) à l'étape 4, appelez Home.getClient(context, userAccount, homeConfig), où le deuxième paramètre est un Lazy<UserAccount>. Cela renvoie une instance de HomeClientWithProvidedAccount, une sous-classe de HomeClient, explicitement liée au compte Google spécifié :

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
         // 1. Create the Account object.
           val androidAccount = Account(userEmail,
                                        GoogleAuthUtil.GOOGLE_ACCOUNT_TYPE)
         // 2. Wrap it in UserAccount.GoogleAccount.
           UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

Si l'utilisateur spécifié n'est pas autorisé, demandez-lui son autorisation en appelant les méthodes suivantes sur l' HomeClientWithProvidedAccount instance :

registerActivityResultCallerForPermissions() avec une référence à l'ActivityResultCaller que vous souhaitez utiliser.
requestPermissions(). L'écran de consentement GHP s'affiche, et l'utilisateur peut accorder son autorisation.

Vous pouvez créer un HomeClient avec un UserAccount et appeler requestPermissions() avec forceLaunch==true pour relancer l'écran de consentement et permettre à l'utilisateur de mettre à jour son autorisation :

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
              UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

client.registerActivityResultCallerForPermissions(this)
client.requestPermissions(forceLaunch= true)

Pour en savoir plus sur la gestion des autorisations des API Home, consultez API Permissions.

Actualiser l'ensemble de l'activité avec le nouveau HomeClient

Une fois que vous disposez d'une nouvelle instance HomeClient, vous devez actualiser l'ensemble de l'activité pour vous réabonner et récupérer les structures, les appareils et les autres données pertinentes associés à ce compte utilisateur.

Enregistrement des caractéristiques et des types d'appareils

La classe FactoryRegistry aide les développeurs à optimiser la taille binaire de leur application en leur permettant d'indiquer explicitement les caractéristiques et les types d'appareils utilisés par leur application.

Notez que les autorisations et le registre d'usine sont dissociés. Par conséquent, les caractéristiques et les types non enregistrés qui sont disponibles pour votre application à l'aide d'autorisations, mais qui ne sont pas inclus dans le registre d'usine, sont inaccessibles à l'aide de l' API Automation et ne sont pas renvoyés dans les appels de méthode groupés traits() ou types().

2. Configurer OAuth

4. API Permissions

Initialiser la maison sur Android Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.