Inicializar a casa no Android

Antes de usar qualquer uma das APIs Home para Android, é necessário inicializar a casa no app. Nesta etapa, você vai criar uma instância singleton de Home para o contexto local.

Apenas uma instância de Home pode estar ativa por vez.

Esse é o ponto de entrada para as APIs Home e também envolve declarar quais características e tipos de dispositivos você pretende usar com as APIs Device & Structure e Automation. Se você está começando a usar o ecossistema do Google Home e não sabe quais características ou tipos de dispositivos registrar, sugerimos alguns dos mais comuns neste guia.

Criar uma instância de casa

Para começar, importe estes pacotes para seu app:

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

Para inicializar as APIs Home:

1. Receba uma referência ao contexto Application. Esse contexto não depende de nenhum ciclo de vida de atividade e vai existir enquanto o app estiver ativo. Para isso, chame getApplicationContext() em um Activity ou Service:

   val context = getApplicationContext()
   

2. Crie uma instância FactoryRegistry com todas as características e tipos de dispositivos que você pretende usar no app.

   Neste guia, sugerimos alguns comuns (tipos de dispositivos de luz, plugue, sensor, interruptor e termostato, além de traços de presença e do Google Assistente para automações), caso você não saiba o que precisa. Para saber mais, consulte Registro de características e tipos de dispositivos.

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

   São necessárias instruções de importação para cada característica individual e tipo de dispositivo registrado aqui. O Android Studio vai pedir que você adicione essas informações.

3. Instancie um HomeConfig usando o contexto de corrotina Dispatchers.IO e sua instância de registro.

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

4. Por fim, crie a instância singleton de Home, que é o ponto de entrada para as APIs, usando o contexto e o HomeConfig.

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

Para evitar erros com sessões inválidas, é importante que apenas uma instância singleton de Home seja criada, envolvendo-a em uma declaração de objeto.

Por exemplo, o app de amostra faz isso desta forma:

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

Login do Google iniciado pelo app

Talvez você queira gerenciar as autenticações do Google do usuário no seu app. Isso permite usar a mesma conta de usuário em vários serviços do Google, como Google Home, Drive, Maps e outros.

Com o login do Google iniciado pelo app, você pode receber uma instância HomeClient explicitamente vinculada a um usuário específico, ignorando o seletor de Conta do Google e a tela de consentimento quando a conta já está autorizada.

Além disso, essa abordagem impede que os usuários vejam duas telas diferentes de seleção de conta: uma do login do app e outra do Google Home.

Para fazer isso, siga as mesmas etapas descritas em Criar uma instância Home, mas em vez de chamar Home.getClient(context, homeConfig) na etapa 4, chame Home.getClient(context, userAccount, homeConfig), em que o segundo parâmetro é um Lazy<UserAccount>. Isso retorna uma instância de HomeClientWithProvidedAccount, uma subclasse de HomeClient, que está explicitamente vinculada à Conta do Google especificada:

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 o usuário especificado não estiver autorizado, peça permissão chamando os seguintes métodos na instância HomeClientWithProvidedAccount:

1. registerActivityResultCallerForPermissions() com uma referência ao ActivityResultCaller que você quer usar.
2. requestPermissions(). Isso abre a tela de consentimento do GHP, em que o usuário pode conceder a permissão.

É possível criar um HomeClient com um UserAccount e chamar requestPermissions() com forceLaunch==true para iniciar a tela de consentimento de novo e permitir que o usuário atualize a concessão de permissões:

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

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

Consulte a API Permissions para mais informações sobre como gerenciar permissões das APIs Home.

Registro de características e tipos de dispositivos

A classe FactoryRegistry ajuda os desenvolvedores a otimizar o tamanho binário do app, permitindo que eles indiquem explicitamente quais características e tipos de dispositivos são usados pelo app.

As permissões e o registro de fábrica são separados. Portanto, características e tipos não registrados que estão disponíveis para seu app usando permissões, mas não incluídos no registro de fábrica, não podem ser acessados usando a API Automation nem são retornados nas chamadas de método em massa traits() ou types().