Inicjowanie domu na urządzeniu z Androidem

Zanim zaczniesz używać interfejsów Home API na Androidzie, musisz zainicjować dom w aplikacji. W tym kroku utworzysz pojedynczą instancję Home dla kontekstu lokalnego.

W danym momencie aktywna może być tylko jedna instancja Home.

Jest to punkt wejścia do interfejsów Home API. Wymaga też zadeklarowania, których cech i typów urządzeń zamierzasz używać w interfejsach Device & Structure API i Automation API. Jeśli dopiero zaczynasz korzystać z ekosystemu Google Home i nie wiesz, jakie cechy lub typy urządzeń zarejestrować, w tym przewodniku znajdziesz kilka najpopularniejszych propozycji.

Tworzenie instancji Home

Aby zacząć, zaimportuj te pakiety do aplikacji:

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

Aby zainicjować interfejsy Home API:

1. Uzyskaj odniesienie do Application kontekstu. Ten kontekst nie zależy od cyklu życia żadnej aktywności i będzie istniał tak długo, jak długo działa aplikacja. Możesz go uzyskać, dzwoniąc pod numer getApplicationContext() w Activity lub Service:

   val context = getApplicationContext()
   

2. Utwórz instancję FactoryRegistry ze wszystkimi cechami i typami urządzeń, których chcesz używać w aplikacji.

   W tym przewodniku proponujemy kilka typowych (typy urządzeń: światło, gniazdko, czujnik, przełącznik i termostat, cechy obecności i Asystenta w przypadku automatyzacji), jeśli nie masz pewności, czego potrzebujesz. Więcej informacji znajdziesz w artykule Rejestracja cech i typów urządzeń.

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

   Wymagane są instrukcje importu dla każdego zarejestrowanego tutaj pojedynczego atrybutu i typu urządzenia (Android Studio powinien wyświetlić prośbę o ich dodanie).

3. Utwórz instancję HomeConfig za pomocą kontekstu korutyny Dispatchers.IO i instancji rejestru.

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

4. Na koniec utwórz instancję singletonu Home, która jest punktem wejścia do interfejsów API, używając kontekstu i HomeConfig.

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

Aby uniknąć błędów związanych z nieprawidłowymi sesjami, ważne jest, aby utworzyć tylko jedną instancję Home, umieszczając ją w deklaracji obiektu.

Na przykład aplikacja przykładowa robi to w ten sposób:

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

Logowanie przez Google inicjowane przez aplikację

Możesz zarządzać uwierzytelnianiem użytkowników w Google w ramach swojej aplikacji. Dzięki temu użytkownicy mogą korzystać z tego samego konta w różnych usługach Google, takich jak Google Home, Dysk, Mapy itp.

Dzięki logowaniu przez Google inicjowanemu przez aplikację możesz uzyskać instancję HomeClient wyraźnie powiązaną z określonym użytkownikiem, co pozwala pominąć selektor kont Google i ekran zgody, gdy konto jest już autoryzowane.

Dodatkowo to podejście zapobiega wyświetlaniu użytkownikom dwóch różnych ekranów wyboru konta – jednego z logowania w aplikacji i jednego z Google Home.

Aby to zrobić, wykonaj te same czynności, które opisaliśmy w artykule Tworzenie instancji Home, ale zamiast wywoływać Home.getClient(context, homeConfig) w kroku 4, wywołaj Home.getClient(context, userAccount, homeConfig), gdzie drugi parametr to Lazy<UserAccount>. Zwraca to instancję klasy HomeClientWithProvidedAccount, podklasy HomeClient, która jest wyraźnie powiązana z określonym kontem Google:

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

Jeśli określony użytkownik nie jest autoryzowany, poproś go o zezwolenie, wywołując te metody na instancji HomeClientWithProvidedAccount:

1. registerActivityResultCallerForPermissions() z odwołaniem do interfejsu ActivityResultCaller, którego chcesz użyć.
2. requestPermissions() Wyświetli się ekran zgody platformy GHP, na którym użytkownik może wyrazić zgodę.

Możesz utworzyć HomeClient za pomocą UserAccount, a następnie wywołać requestPermissions() z forceLaunch==true, aby ponownie wyświetlić ekran zgody i umożliwić użytkownikowi zaktualizowanie przyznanych uprawnień:

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

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

Więcej informacji o zarządzaniu uprawnieniami interfejsów API Home znajdziesz w artykule Interfejs API uprawnień.

Rejestracja cech i typów urządzeń

Klasa FactoryRegistry pomaga deweloperom optymalizować rozmiar pliku binarnego aplikacji, umożliwiając im wyraźne wskazanie, które cechy i typy urządzeń są używane przez aplikację.

Pamiętaj, że uprawnienia i rejestr fabryczny są od siebie niezależne. Dlatego niezarejestrowane cechy i typy, które są dostępne dla aplikacji za pomocą uprawnień, ale nie są uwzględnione w rejestrze fabrycznym, są niedostępne za pomocą interfejsu Automation API ani nie są zwracane w wywołaniach metod zbiorczych traits() ani types().