Berechtigungen-API unter Android

Bevor Sie eine der Home APIs für Android verwenden können, muss die App die Berechtigung haben, auf Geräte im Zuhause des Nutzers zuzugreifen, die in der API als Gebäude bezeichnet werden. Mit der Permissions API kann der Nutzer mit seinem Google-Konto Apps Zugriff auf Geräte in seinem Zuhause gewähren.

Im Berechtigungsablauf kann der Nutzer eine Struktur erstellen, falls noch keine eingerichtet wurde, ohne Google Home app (GHA) verwenden zu müssen.

Permissions API einbinden

Bevor Sie fortfahren, müssen Sie die Schritte unter Zuhause auf Android initialisieren ausführen. Die homeManager-Instanz aus diesem Schritt wird in allen Beispielen für Berechtigungen verwendet.

Registrieren Sie zuerst ein ActivityResultCaller mit dem SDK. So wird das beispielsweise in der Beispiel-App gehandhabt:

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

Berechtigungen prüfen

Bevor Sie Berechtigungen anfordern, sollten Sie prüfen, ob der Nutzer der App bereits die Einwilligung zum Zugriff auf die Struktur erteilt hat. Rufen Sie dazu die Methode hasPermissions() der Home-Instanz auf, um ein Flow mit PermissionsState-Werten abzurufen:

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 bei der Prüfung PermissionsState mit dem Wert NOT_GRANTED oder PERMISSIONS_STATE_UNAVAILABLE zurückgegeben wird, bedeutet das, dass entweder der Nutzer oder die Anwendung keinen Zugriff auf die Struktur hat. Wenn bei der Prüfung PermissionsState mit dem Wert GRANTED zurückgegeben wird, ein nachfolgender Aufruf von structures() aber 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

Ihrer App muss die Berechtigung erteilt werden, damit sie auf Gebäude und Geräte in einem bestimmten Gebäude zugreifen kann.

Wenn der Nutzer noch keine Berechtigungen erteilt hat, verwenden Sie 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 Berechtigungs-UI richtig gestartet werden kann, müssen Sie OAuth für Ihre App eingerichtet haben.

Berechtigungen erteilen

Jetzt sollten Sie Ihre App ausführen und einen Nutzer um die Erteilung von Berechtigungen bitten 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 Sie Ihre App im Google Home Developer Console registriert haben.

Die Registrierung von Developer Console 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, befindet sie sich im Status nicht bestätigt. Wir empfehlen, die Home-APIs so zu testen:

• 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 bestätigte 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 Developer Console). Alle Geräte in einem Gebäude werden 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,wird sie als verifiziert angezeigt. Dieser Status ist erforderlich, um eine App in der Produktion zu starten:

• 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 ist, werden durch den Aufruf von requestPermissions() durch die App die folgenden Dialogfelder ausgelöst:

1. Der Nutzer wird aufgefordert, das Google-Konto auszuwählen, das er verwenden möchte.
2. Der Nutzer wird aufgefordert, das Zuhause auszuwählen, auf das die App zugreifen soll.
   1. Bei einer nicht bestätigten App sind alle von den Home-APIs unterstützten Gerätetypen für die App verfügbar.
   2. Bei einer überprüften App kann der Nutzer nur den Gerätetypen Berechtigungen erteilen, die in Developer Console genehmigt wurden.
   3. Bei sensiblen Gerätetypen, auf die die App Zugriff hat, kann der Nutzer den Zugriff pro Gerät einschränken. Wenn ein Nutzer beispielsweise drei Schlösser hat, kann er nur Zugriff auf eines dieser Schlösser gewähren.

Nachdem die Berechtigung erteilt wurde, kann die App die Home-APIs verwenden, um den Status der Geräte in der Struktur zu lesen und sie zu steuern. Wenn der Nutzer der App keine Berechtigung für einen bestimmten Gerätetyp oder ein sensibles Gerät erteilt, kann die App nicht über die Home APIs darauf zugreifen, es steuern oder automatisieren.

Berechtigungen ändern

Wenn Sie die Berechtigung zum Zugriff auf Geräte in einer anderen Struktur erteilen möchten, kann die Kontoauswahl gestartet werden, damit der Nutzer das Google-Konto und die Struktur auswählen kann, zu denen er wechseln möchte. Während dieses Vorgangs wird dem Nutzer der Zustimmungsbildschirm noch einmal angezeigt, auch wenn er bereits seine Einwilligung gegeben hat.

Dazu rufen Sie requestPermissions() noch einmal auf und setzen das Flag forceLaunch auf true:

homeManager.requestPermissions(forceLaunch=true)

Berechtigungen mit Strukturhinweisen ändern

Mithilfe von Strukturhinweisen kann eine App eine bestimmte Struktur vorab auswählen oder die Liste der verfügbaren Strukturen einschränken, wenn eine inkrementelle Änderung der Berechtigungen der Home-APIs des Nutzers angefordert wird. Wenn Sie Strukturparameter in die Autorisierungsanfrage einfügen, wird im Berechtigungsdialog automatisch die ausgewählte Struktur angezeigt. Das reduziert die Reibung für Nutzer und verhindert Konfigurationsfehler.

Die Strukturierungshinweise werden mit der Datenklasse ConsentScreenOptions verwaltet. Die Klasse ConsentScreenOptions akzeptiert die folgenden Konfigurationsparameter:

• structureId: Die spezifische Struktur-ID, die im Berechtigungsdialogfeld vorausgewählt werden soll. Sie erhalten diese Informationen, indem Sie die Struktureigenschaften der Struktur prüfen, die aktualisiert wird.
• allowedStructureIds: Eine Liste von Struktur-IDs. Wenn angegeben, werden im Berechtigungsdialog nur die Strukturen in dieser Liste angezeigt. In den meisten Fällen kann dies unspezifiziert bleiben, es sei denn, Sie möchten sicherstellen, dass der Nutzer innerhalb einer bereits gewährten Liste von Gebäuden bleibt.
• allowStructureChange: Gibt an, ob der Nutzer die vorausgewählte Struktur ändern darf. Legen Sie diesen Wert auf true fest, wenn in den meisten Fällen mindestens einer der Werte allowedStructureIds und structureId angegeben ist, um das natürliche Verhalten des Nutzers zu unterstützen.

Übergeben Sie dieses Objekt als optionalen Parameter im requestPermissions()-Aufruf, wobei das Flag forceLaunch auf true 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(forceLaunch=true, consentOptions)

Dem Nutzer wird der Zustimmungsbildschirm bereits gefiltert nach der im ConsentScreenOptions-Objekt angegebenen Struktur angezeigt.

Nutzern erlauben, Strukturen mit Strukturhinweisen zu wechseln

Wenn ein Nutzer mehrere Strukturen in einer App hat und Sie eine davon vorauswählen möchten, ihm aber trotzdem erlauben möchten, zwischen den verfügbaren Strukturen zu wechseln, aktivieren Sie Strukturänderungen mit dem Flag allowStructureChange und geben Sie eine Liste der Strukturen 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 Seite „Mein Konto“ > „Daten und Datenschutz“ > „Drittanbieter-Apps und ‑Dienste“. Dadurch wird das OAuth-Token widerrufen, das bei der ursprünglichen Einwilligung ausgestellt wurde, und der Zugriff auf alle Instanzen der App, die der Nutzer auf allen Oberflächen (Smartphones) und in allen Strukturen verwendet hat, wird widerrufen.

   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 > Verknüpfte Apps. Wenn Sie in der GHA auf settings klicken, gelangen Sie zur Seite Einstellungen. Klicken Sie dort auf die Kachel Verknüpfte Apps. Sie werden dann zu einer Seite weitergeleitet, die dem Zustimmungsbildschirm ähnelt. Auf dieser Seite kann der Nutzer den Zugriff auf die App entfernen. Er kann auf dieser Seite auch ändern, auf welche Gerätetypen oder bestimmte sensible Geräte die App zugreifen kann.

Gerätetypen ansehen, für die ein Nutzer Berechtigungen erteilt hat

Im Google Home-Ökosystem können Nutzer für die meisten Gerätetypen Berechtigungen für alle Geräte dieses Typs gleichzeitig erteilen. Bei sicherheits- oder datenschutzrelevanten Gerätetypen wie Schlössern, Kameras oder Türklingeln müssen Nutzer ihnen einzeln Berechtigungen erteilen.

Mit der Funktion consentedDeviceTypes() auf Strukturebene können Sie ermitteln, ob ein Nutzer die Berechtigung zum Zugriff auf einen vertraulichen 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
            }
        }
    }
}

„Ok Google“-Berechtigungen

Der Befehl okGoogle ist ein Befehl auf Geräteebene und kann verwendet werden, um jedes Gerät in der Struktur 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.

Hinweise, wenn ein Nutzer alle Berechtigungen widerruft

Wenn der Nutzer die vollständigen Berechtigungen widerruft, funktionieren alle vorhandenen Automatisierungen nicht mehr. Wenn der Nutzer den Zugriff auf bestimmte Geräte widerruft, funktionieren auch 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 bisherigen Daten entfernt werden, einschließlich aller in der Anwendung zwischengespeicherten Daten.