Inizializzare la casa su Android

Prima di utilizzare una delle API Home per Android, devi inizializzare la casa nella tua app. In questo passaggio, creerai un'istanza singleton di Home per il contesto locale.

Deve essere attiva una sola istanza di Home alla volta.

Questo è il punto di accesso alle API Home e comporta anche la dichiarazione di quali tratti e tipi di dispositivi intendi utilizzare con le API Device & Structure e Automation. Se hai appena iniziato a utilizzare l'ecosistema Google Home e non sai quali tratti o tipi di dispositivi registrare, in questa guida abbiamo suggerito alcuni dei più comuni.

Creare un'istanza Home

Per iniziare, importa questi pacchetti nella tua app:

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

Per inizializzare le API Home:

1. Ottieni un riferimento al contesto Application. Questo contesto non dipende da alcun ciclo di vita dell'attività e rimarrà attivo finché la tua app è attiva. Puoi ottenerlo chiamando getApplicationContext() entro le Activity o le Service:

   val context = getApplicationContext()
   

2. Crea un'istanza FactoryRegistry con tutti i tratti e i tipi di dispositivi che intendi utilizzare nella tua app.

   Per questa guida, abbiamo suggerito alcuni tipi comuni (dispositivi di tipo Luce, Presa, Sensore, Interruttore e Termostato, tratti di presenza e dell'assistente per le automazioni), nel caso in cui non sapessi cosa ti serve. Per saperne di più, vedi Registrazione di tratti e tipi di dispositivi.

   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))
   

   Sono richieste le istruzioni di importazione per ogni singolo tratto e tipo di dispositivo registrato qui (Android Studio dovrebbe chiederti di aggiungerle).

3. Crea un'istanza di HomeConfig utilizzando il contesto della coroutine Dispatchers.IO e l'istanza del registro.

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

4. Infine, crea l'istanza singleton di Home, che è il punto di accesso alle API, utilizzando il contesto e HomeConfig.

   val homeManager: HomeClient = Home.getClient(context, homeConfig)
   

Per evitare errori con sessioni non valide, è importante che venga creata solo un'istanza singleton di Home, racchiudendola in una dichiarazione di oggetto.

Ad esempio, l'app di esempio lo fa in questo modo:

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

Accesso Google avviato dall'app

Potresti voler gestire le autenticazioni Google dell'utente all'interno della tua app. In questo modo, puoi utilizzare lo stesso account utente in vari servizi Google, ad esempio Google Home, Drive, Maps e così via.

Con l'accesso con Google avviato dall'app, puoi ottenere un'istanza HomeClient collegata esplicitamente a un determinato utente, bypassando così il selettore dell'Account Google e la schermata del consenso quando l'account è già autorizzato.

Inoltre, questo approccio impedisce agli utenti di visualizzare due diverse schermate di selezione dell'account: una dall'accesso dell'app e una da Google Home.

Per farlo, segui gli stessi passaggi descritti in Crea un'istanza Home, ma anziché chiamare Home.getClient(context, homeConfig) nel passaggio 4, chiama Home.getClient(context, userAccount, homeConfig), dove il secondo parametro è un Lazy<UserAccount>. Viene restituita un'istanza di HomeClientWithProvidedAccount, una sottoclasse di HomeClient, esplicitamente collegata all'Account Google specificato:

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()
     )

Se l'utente specificato non è autorizzato, chiedi l'autorizzazione chiamando i seguenti metodi sull'istanza HomeClientWithProvidedAccount:

1. registerActivityResultCallerForPermissions() con un riferimento a ActivityResultCaller che vuoi utilizzare.
2. requestPermissions(). Viene visualizzata la schermata di consenso di Google Health Connect, in cui l'utente può concedere l'autorizzazione.

Puoi creare un HomeClient con un UserAccount e poi chiamare requestPermissions() con forceLaunch==true per avviare di nuovo la schermata del consenso e consentire all'utente di aggiornare la concessione delle autorizzazioni:

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

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

Per ulteriori informazioni sulla gestione delle autorizzazioni delle API Home, consulta la API Permissions.

Registrazione di tratti e tipi di dispositivi

La classe FactoryRegistry aiuta gli sviluppatori a ottimizzare le dimensioni del file binario dell'app consentendo loro di indicare esplicitamente quali caratteristiche e tipi di dispositivi vengono utilizzati dalla loro app.

Tieni presente che le autorizzazioni e il registro di fabbrica sono disaccoppiati. Pertanto, i tipi e le caratteristiche non registrati disponibili per la tua app tramite le autorizzazioni, ma non inclusi nel registro di fabbrica, non sono accessibili tramite l'API Automation e non vengono restituiti nelle chiamate di metodi collettivi traits() o types().