Berechtigungen-API unter Android

Bevor eine der Home APIs für Android verwendet werden kann, muss die App die Berechtigung haben, auf Geräte im Zuhause des Nutzers zuzugreifen. In der API wird dies als Gebäude bezeichnet. Mit der Permissions API kann der Nutzer über sein Google-Konto Home APIs-Apps Zugriff auf Geräte in seinem Zuhause gewähren.

Über den Berechtigungsablauf kann der Nutzer ein Gebäude erstellen und ihm eine Adresse zuweisen, falls noch keine eingerichtet wurde, ohne die Google Home app (GHA) verwenden zu müssen.

Permissions API einbinden

Bevor du fortfährst, musst du die Schritte unter Zuhause auf Android-Geräten initialisieren ausgeführt haben. Die Instanz homeManager aus diesem Schritt wird in allen Berechtigungsbeispielen hier verwendet.

Registrieren Sie zuerst einen ActivityResultCaller beim SDK. In der Beispiel-App wird das so gehandhabt:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Berechtigungen prüfen

Bevor du Berechtigungen anforderst, solltest du prüfen, ob der Nutzer der App bereits die Einwilligung für den Zugriff auf das Gebäude erteilt hat. Rufen Sie dazu die Methode hasPermissions() der Home-Instanz auf, um eine Flow mit PermissionsState-Werten zu erhalten:

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
          println("Permissions state unavailable, request permissions")

      PermissionsState.NOT_GRANTED ->
          println("OAuth permission is enabled but not granted yet, request permissions")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

Wenn die Prüfung den PermissionsState-Wert NOT_GRANTED oder PERMISSIONS_STATE_UNAVAILABLE zurückgibt, bedeutet dies, dass entweder der Nutzer oder die Anwendung keinen Zugriff auf das Gebäude hat. Wenn die Prüfung den PermissionsState-Wert GRANTED zurückgibt, ein nachfolgender Aufruf von structures() jedoch keine Strukturen zurückgibt, hat der Nutzer entweder den Zugriff auf die App über die Einstellungsseite GHA widerrufen oder er hat nicht den erforderlichen Zugriff.

Berechtigungen anfordern

Deiner App muss die Berechtigung erteilt werden, auf Gebäude und Geräte innerhalb eines bestimmten Gebäudes zuzugreifen.

Wenn der Nutzer die Berechtigungen noch nicht erteilt hat, verwende die Methode requestPermissions() der Home-Instanz, um die Berechtigungs-UI zu starten und das Ergebnis zu verarbeiten:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

Damit die Benutzeroberfläche für Berechtigungen ordnungsgemäß gestartet werden kann, müssen Sie OAuth für Ihre App eingerichtet haben.

Die Benutzeroberfläche für die Berechtigungseinwilligung wird in der mit HomeClient.setLocale() konfigurierten Sprache gerendert. Wenn keine Sprache festgelegt ist, wird die Sprache der App oder des Geräts verwendet. Wenn Sie den Zustimmungsbildschirm in einer bestimmten Sprache anzeigen möchten, rufen Sie setLocale() in Ihrer HomeClient-Instanz auf, bevor Sie requestPermissions() aufrufen. Weitere Informationen finden Sie unter App-Sprache konfigurieren.

Berechtigungen erteilen

Jetzt sollten Sie Ihre App ausführen und einen Nutzer Berechtigungen gewähren lassen können. Die Art der Nutzer, die Berechtigungen erteilen können, und die Gerätetypen, für die Berechtigungen erteilt werden können, hängen davon ab, ob du deine App in der Google Home Developer Console registriert hast.

Die Developer Console-Registrierung ist erforderlich, um eine App mit den Home-APIs zu veröffentlichen. Sie ist nicht erforderlich, um die Home APIs zu testen und zu verwenden.

Wenn eine App nicht in der Developer Console registriert ist, hat sie den Status Nicht bestätigt. Dies wird zum Testen der Verwendung der Home APIs empfohlen:

• Nur Nutzer, die in der OAuth-Konsole als Testnutzer registriert sind, können Berechtigungen für die App erteilen. Für eine nicht bestätigte App gilt ein Limit von 100 Testnutzern.

• Eine nicht überprüfte App hat Zugriff auf Geräte aller Gerätetypen, die von OAuth für die Home APIs unterstützt werden (die Liste der Gerätetypen in der Developer Console). Der Zugriff wird für alle Geräte in einem Gebäude gewährt.

Wenn eine App in der Developer Console registriert ist und für den Zugriff auf einen oder mehrere Gerätetypen genehmigt wurde und die Markenüberprüfung für OAuth abgeschlossen wurde, befindet sie sich im Status Bestätigt. Dieser Status ist erforderlich, um eine App in der Produktion einzuführen:

• Die Beschränkungen für Testnutzer gelten nicht mehr. Jeder Nutzer kann der App die Berechtigung erteilen.
• Der Nutzer kann nur Berechtigungen für die Gerätetypen erteilen, die in der Developer Console genehmigt wurden.

Nachdem OAuth eingerichtet wurde, löst der Aufruf von requestPermissions() durch die App die folgenden Dialogfelder aus:

1. Der Nutzer wird aufgefordert, das Google-Konto auszuwählen, das er verwenden möchte.
2. Der Nutzer wird aufgefordert, das Gebäude auszuwählen, auf das die App zugreifen darf.
   1. Für eine nicht verifizierte App sind alle von den Home APIs unterstützten Gerätetypen verfügbar.
   2. Bei einer verifizierten App kann der Nutzer nur die Berechtigung für die Gerätetypen erteilen, die in Developer Console genehmigt wurden.
   3. Bei sensiblen Gerätetypen, auf die die App Zugriff hat, kann der Nutzer den Zugriff auf einzelne Geräte beschränken. Wenn ein Nutzer beispielsweise drei Schlösser hat, kann er den Zugriff auf nur eines dieser Schlösser gewähren.

Nachdem die Berechtigung erteilt wurde, kann die App die Home APIs verwenden, um den Status der Geräte im Gebäude auszulesen und die Geräte zu steuern. Wenn der Nutzer der App keine Berechtigung für einen bestimmten Gerätetyp oder ein bestimmtes vertrauliches Gerät erteilt, kann die App nicht über die Home APIs darauf zugreifen, es steuern oder automatisieren.

Berechtigungen ändern

Wenn du Zugriff auf Geräte in einem anderen Gebäude gewähren möchtest, kannst du die Kontoauswahl starten, damit der Nutzer das Google-Konto und das Gebäude auswählen kann, zu dem er wechseln möchte. Während dieses Vorgangs wird dem Nutzer der Zustimmungsbildschirm noch einmal angezeigt, auch wenn die Zustimmung bereits erteilt wurde.

Dazu rufen Sie requestPermissions() noch einmal auf und setzen forcePermissionFlow auf ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Berechtigungen mit Structure Hinting ändern

Mit Structure Hinting kann eine App ein bestimmtes Gebäude vorab auswählen oder die Liste der verfügbaren Gebäude einschränken, wenn eine inkrementelle Änderung der Berechtigungen des Nutzers für die Home APIs angefordert wird. Wenn du Strukturparameter in die Autorisierungsanfrage einfügst, wird im Dialogfeld für die Berechtigungen automatisch die ausgewählte Struktur angezeigt. Das reduziert die Reibung für den Nutzer und verhindert Konfigurationsfehler.

Structure Hinting wird mit der Datenklasse ConsentScreenOptions verwaltet. Die Klasse ConsentScreenOptions akzeptiert die folgenden Konfigurationsparameter:

• structureId: Die ID des Gebäudes, das im Berechtigungsdialogfeld vorausgewählt werden soll. Diese findest du in den Gebäudeeigenschaften des Gebäudes, das aktualisiert wird.
• allowedStructureIds: Eine Liste von Gebäude-IDs. Wenn angegeben, werden im Berechtigungsdialogfeld nur die in dieser Liste enthaltenen Gebäude angezeigt. In den meisten Fällen kann dies nicht angegeben werden, es sei denn, du möchtest sicherstellen, dass der Nutzer nur auf eine bereits gewährte Liste von Gebäuden zugreifen kann.
• allowStructureChange: Bestimmt, ob der Nutzer die vorausgewählte Struktur ändern darf. Legen Sie hier true fest, wenn in den meisten Fällen mindestens eine der Optionen allowedStructureIds und structureId angegeben ist, um ein natürliches Verhalten für den Nutzer zu unterstützen.

Übergeben Sie dieses Objekt als optionalen Parameter im requestPermissions()-Aufruf, wobei forcePermissionFlow auf ForcePermissionFlow.FORCE_LAUNCH gesetzt ist:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

Dem Nutzer wird der Zustimmungsbildschirm angezeigt, der bereits nach dem im ConsentScreenOptions-Objekt angegebenen Gebäude gefiltert ist.

Nutzern erlauben, Gebäude mit Structure Hinting zu wechseln

Wenn ein Nutzer mehrere Gebäude in einer App hat und du eines davon vorauswählen möchtest, ihm aber trotzdem die Möglichkeit geben möchtest, zwischen seinen verfügbaren Gebäuden zu wechseln, aktiviere Gebäudeänderungen mit dem Flag allowStructureChange und gib eine Liste von Gebäuden in allowedStructureIds an:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

Berechtigungen widerrufen

Nutzer können zuvor gewährten Zugriff widerrufen:

1. Über die Google-Kontoeinstellungen > „Daten und Datenschutz“ > „Drittanbieter-Apps und ‑Dienste“. Dadurch wird das OAuth-Token widerrufen, das bei der ursprünglichen Einwilligung ausgestellt wurde. Außerdem wird der Zugriff auf alle Instanzen der App widerrufen, die der Nutzer auf allen Oberflächen (Smartphones) und in allen Gebäuden verwendet hat.

   Der Nutzer kann über einen Deeplink mit dem folgenden URL-Schema zur Unterseite Drittanbieter-Apps und ‑Dienste weitergeleitet werden:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

2. Über die Seite GHA > Einstellungen > Verbundene Apps. Wenn Sie in der GHA auf settings klicken, gelangen Sie zur Seite Einstellungen. Klicken Sie dort auf die Kachel Verknüpfte Apps. Sie gelangen dann auf eine Seite, die dem Zustimmungsbildschirm ähnelt. Auf dieser Seite kann der Nutzer den Zugriff auf die App entfernen. Außerdem kann er hier ändern, auf welche Gerätetypen oder bestimmten sensiblen Geräte die App zugreifen darf.

Löschen und Exportieren von Nutzerdaten

Die Plattform verwaltet automatisch das Löschen von Backend-Daten, wenn ein Nutzer sein Google-Konto löscht oder ein Gebäude verlässt:

• Wenn der gelöschte Nutzer der alleinige Eigentümer eines Gebäudes ist, löscht die Plattform das Gebäude und die zugehörigen Geräte.
• Wenn andere Eigentümer in einem gemeinsamen Gebäude verbleiben, bleiben das Gebäude und die gemeinsam genutzten Geräte für die verbleibenden Mitglieder erhalten. Die Plattform entfernt die Mitgliedschaft des ausgeschiedenen Nutzers und hebt die Verknüpfung aller Cloud-to-cloud-Geräte von Drittanbietern auf, die nur über die Anmeldedaten dieses Nutzers verbunden sind.
• Durch das Löschen des Kontos werden die Gebäudedaten und App-Berechtigungen des Nutzers sofort und endgültig entfernt. Auch wenn der Nutzer sein Google-Konto später wiederherstellt, werden seine Gebäude und Berechtigungen nicht wiederhergestellt.

Die Home APIs bieten keine Endpunkte zum Exportieren oder Löschen der Google-Kontodaten eines Nutzers. Nutzer mit einem Google-Konto können ihre Google Home-Daten über Google Datenexport exportieren und die Kontolöschung in den Google-Kontoeinstellungen verwalten.

Gerätetypen aufrufen, für die ein Nutzer Berechtigungen gewährt hat

In der Google Home-Umgebung können Nutzer für die meisten Gerätetypen Berechtigungen für alle Geräte dieses Typs gleichzeitig gewähren. Für sensible oder eingeschränkte Gerätetypen wie Schlösser, Kameras oder Türklingeln müssen Nutzer die Berechtigungen einzeln erteilen.

Mit der Funktion consentedDeviceTypes() auf Gebäudeebene kannst du feststellen, ob ein Nutzer die Berechtigung für den Zugriff auf einen sensiblen oder eingeschränkten Gerätetyp erteilt hat:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

„Hey Google“-Berechtigungen

Der Befehl okGoogle ist ein Befehl auf Geräteebene und kann verwendet werden, um jedes Gerät im Gebäude zu automatisieren. Eine Home APIs-App hat jedoch möglicherweise nicht auf alle Geräte Zugriff. In der folgenden Tabelle wird beschrieben, wie Berechtigungen in solchen Fällen erzwungen werden.

Anleitung für den Fall, dass der Nutzer die vollständigen Berechtigungen widerruft

Wenn der Nutzer die vollständigen Berechtigungen widerruft, funktionieren alle vorhandenen automatisierten Abläufe nicht mehr. Wenn der Nutzer den Zugriff auf bestimmte Geräte widerruft, funktionieren die mit diesen Geräten verknüpften Auslöser, Bedingungen und Aktionen nicht mehr.

Prüfen Sie bei jedem Start der App, ob die Berechtigungen noch gültig sind. Wenn sie widerrufen wurden, müssen alle vorherigen Daten entfernt werden, einschließlich aller in der Anwendung im Cache gespeicherten Daten.

Wenn der Zugriff auf das Gebäude widerrufen wird, wird ein StructureAccessRevokedEvent an dein Cloud-Backend gesendet. Informationen zum End-to-End-Workflow für den Widerruf von Partner-Cloud- und mobilen Apps findest du unter Struktur-Berechtigungen.