Zuhause auf Android-Geräten initialisieren

Bevor Sie die Home-APIs für Android verwenden können, müssen Sie das Zuhause in Ihrer App initialisieren. In diesem Schritt erstellen Sie eine Singleton-Instanz von Home für den lokalen Kontext.

Es sollte immer nur eine Instanz von Home aktiv sein.

Dies ist der Einstiegspunkt für die Home APIs. Außerdem müssen Sie angeben, welche Traits und Gerätetypen Sie mit der Device & Structure API und der Automation API verwenden möchten. Wenn du gerade erst mit dem Google Home-Ökosystem beginnst und nicht sicher bist, welche Merkmale oder Gerätetypen du registrieren sollst, haben wir in diesem Leitfaden einige der häufigsten Vorschläge gemacht.

Home-Instanz erstellen

Importieren Sie zuerst diese Pakete in Ihre App:

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

So initialisieren Sie die Home APIs:

Rufen Sie einen Verweis auf den Kontext Application ab. Dieser Kontext ist nicht vom Aktivitätslebenszyklus abhängig und ist so lange verfügbar, wie Ihre App aktiv ist. Sie können sie abrufen, indem Sie getApplicationContext() in einem Activity oder Service aufrufen:
```
val context = getApplicationContext()
```

Erstelle eine FactoryRegistry-Instanz mit allen Attributen und Gerätetypen, die du in deiner App verwenden möchtest.

In dieser Anleitung haben wir einige gängige Gerätetypen (Gerätetypen „Light“, „Plug“, „Sensor“, „Switch“ und „Thermostat“, Anwesenheits- und Assistant-Merkmale für Automatisierungen) vorgeschlagen, falls Sie sich nicht sicher sind, was Sie benötigen. Weitere Informationen finden Sie unter Registrierung von Merkmalen und Gerätetypen.

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

Für jedes einzelne Merkmal und jeden hier registrierten Gerätetyp sind Importanweisungen erforderlich (Android Studio sollte Sie auffordern, diese hinzuzufügen).

Instanziieren Sie HomeConfig mit dem Coroutinenkontext Dispatchers.IO und Ihrer Registry-Instanz.

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

Erstellen Sie schließlich die Singleton-Instanz von Home, dem Einstiegspunkt für die APIs, mit dem Kontext und dem HomeConfig.
```
val homeManager: HomeClient = Home.getClient(context, homeConfig)
```

Um Fehler bei ungültigen Sitzungen zu vermeiden, ist es wichtig, dass nur eine Singleton-Instanz von Home erstellt wird, indem sie in eine Objektdeklaration eingeschlossen wird.

In der Beispiel-App wird dies beispielsweise so umgesetzt:

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

Von der App initiierte Google-Anmeldung

Möglicherweise möchten Sie die Google-Authentifizierungen Ihrer Nutzer in Ihrer App verwalten. So können Sie dasselbe Nutzerkonto für verschiedene Google-Dienste wie Google Home, Drive und Maps verwenden.

Mit der von der App initiierten Google-Anmeldung können Sie eine HomeClient-Instanz abrufen, die explizit mit einem bestimmten Nutzer verknüpft ist. So werden die Google-Kontoauswahl und der Einwilligungsbildschirm umgangen, wenn das Konto bereits autorisiert ist.

Außerdem wird so verhindert, dass Nutzer zwei verschiedene Bildschirme zur Kontoauswahl sehen – einen von der Anmeldung der App und einen von Google Home.

Dazu müssen Sie sich den Abschnitt Nutzer mit „Über Google anmelden“ authentifizieren ansehen und die folgenden Schritte ausführen:

OAuth-Webanwendungs-Client-ID erstellen

Öffnen Sie die Google Cloud Console.
- Rufen Sie in der Google Cloud Console die Seite „Anmeldedaten“ auf.
- Wählen Sie ein vorhandenes Projekt aus oder erstellen Sie ein neues.
OAuth-Zustimmungsbildschirm konfigurieren (falls noch nicht geschehen)
- Bevor Sie Anmeldedaten erstellen, müssen Sie dafür sorgen, dass der OAuth-Zustimmungsbildschirm mit den Details Ihrer App konfiguriert ist, einschließlich der URLs zur Datenschutzerklärung und zu den Nutzungsbedingungen.
OAuth-Client-ID erstellen (Typ „Webanwendung“)
- Klicken Sie auf der Seite „Anmeldedaten“ auf + CREATE CREDENTIALS und wählen Sie im Drop-down-Menü OAuth-Client-ID aus.
- Wählen Sie als Anwendungstyp die Option Webanwendung aus.
- Geben Sie einen Namen für Ihren Webclient ein, z.B. „My App Web Backend“).
- Klicken Sie auf „Erstellen“.
Client-ID abrufen
- Nach der Erstellung wird in der Konsole die neue Client-ID angezeigt. Diesen Wert verwenden Sie in Ihrer Android-Anwendung (z. B. {project number}-.....apps.googleusercontent.com).
- Es wird empfohlen, die Client-ID extern (z. B. in build.gradle) zu speichern, anstatt sie direkt hartzucodieren.

Google Log-in-Anfrage instanziieren

Verwenden Sie die Web-App-ID, um eine Google-Anmeldeanfrage zu erstellen:

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

Ablauf „Über Google anmelden“ erstellen

Verwenden Sie CredentialManager, um eine Sign in with Google-Anfrage auszuführen und den Anmeldevorgang zu implementieren. Sobald der Nutzer ein Konto ausgewählt hat, extrahieren Sie seine E‑Mail-Adresse aus dem resultierenden Google-ID-Token, um ein android.accounts.Account zu erstellen. Mit diesem Konto wird dann eine HomeClient-Instanz initialisiert, die speziell mit dem angemeldeten Nutzer verknüpft ist.

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

Neue HomeClient-Instanz abrufen

Folge derselben Anleitung wie unter Home-Instanz erstellen beschrieben. Rufe jedoch in Schritt 4 anstelle von Home.getClient(context, homeConfig) die Funktion Home.getClient(context, userAccount, homeConfig) auf. Der zweite Parameter ist dabei ein Lazy<UserAccount>. Dadurch wird eine Instanz von HomeClientWithProvidedAccount zurückgegeben, einer Unterklasse von HomeClient, die explizit mit dem angegebenen Google-Konto verknüpft ist:

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

Wenn der angegebene Nutzer nicht autorisiert ist, fordern Sie ihn auf, seine Einwilligung zu erteilen, indem Sie die folgenden Methoden für die HomeClientWithProvidedAccount-Instanz aufrufen:

registerActivityResultCallerForPermissions() mit einem Verweis auf den ActivityResultCaller, den Sie verwenden möchten.
requestPermissions(). Dadurch wird der GHP-Zustimmungsbildschirm aufgerufen, auf dem der Nutzer seine Einwilligung erteilen kann.

Sie können ein HomeClient mit einem UserAccount erstellen und dann requestPermissions() mit forceLaunch==true aufrufen, um den Einwilligungsbildschirm noch einmal zu starten, damit der Nutzer seine Berechtigungen aktualisieren kann:

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

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

Weitere Informationen zum Verwalten von Berechtigungen für Home-APIs finden Sie unter Permissions API.

Aktualisieren Sie die gesamte Aktivität mit dem neuen HomeClient.

Sobald Sie eine neue HomeClient-Instanz haben, müssen Sie die gesamte Aktivität aktualisieren, um das Abo noch einmal abzuschließen und die vollständigen Strukturen, Geräte und anderen relevanten Daten abzurufen, die mit diesem Nutzerkonto verknüpft sind.

Registrierung von Traits und Gerätetypen

Mit der Klasse FactoryRegistry können Entwickler die Größe des App-Binärprogramms optimieren, indem sie explizit angeben, welche Merkmale und Gerätetypen von ihrer App verwendet werden.

Berechtigungen und die Werksregistrierung sind voneinander entkoppelt. Daher sind nicht registrierte Merkmale und Typen, die für Ihre App über Berechtigungen verfügbar sind, aber nicht in der Werksregistrierung enthalten sind, über die Automation API nicht zugänglich und werden auch nicht in den Bulk-Methodenaufrufen traits() oder types() zurückgegeben.

Zurück

2. OAuth einrichten

Weiter

4. Berechtigungen-API

Zuhause auf Android-Geräten initialisieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.