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 Struktur bezeichnet. Mit der Berechtigungen-API kann der Nutzer über sein Google-Konto Apps, die die Home-APIs verwenden, Zugriff auf Geräte in seinem Zuhause gewähren.

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

Berechtigungen-API einbinden

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

Registrieren Sie zuerst einen ActivityResultCaller beim 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 Zustimmung zum Zugriff auf die Struktur erteilt hat. Rufen Sie dazu die Methode hasPermissions() der Home-Instanz auf, um einen Flow von 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 die Prüfung den Wert NOT_GRANTED oder PERMISSIONS_STATE_UNAVAILABLE für PermissionsState zurückgibt, hat entweder der Nutzer oder die Anwendung keinen Zugriff auf die Struktur. Wenn die Prüfung den Wert PermissionsState für GRANTED zurückgibt, ein nachfolgender Aufruf von structures() aber keine Strukturen zurückgibt, hat der Nutzer entweder den Zugriff auf die App über die Einstellungsseite der GHA widerrufen oder er hat nicht den erforderlichen Zugriff.

Berechtigungen anfordern

Ihrer App muss die Berechtigung erteilt werden, auf Strukturen und Geräte innerhalb einer bestimmten Struktur zuzugreifen.

Wenn der Nutzer noch keine Berechtigungen erteilt hat, verwenden Sie die requestPermissions() Methode 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 ordnungsgemäß gestartet werden kann, müssen Sie OAuth bereits eingerichtet für Ihre App haben.

Berechtigungen erteilen

Jetzt sollten Sie Ihre App ausführen und einen Nutzer Berechtigungen erteilen lassen können. Die Art der Nutzer, die Berechtigungen erteilen können, und die Gerätetypen, für die Berechtigungen erteilt werden können, unterscheiden sich je nachdem, ob Sie Ihre App in der Google Home Developer Consoleregistriert haben.

Developer Console Registrierung ist erforderlich, um eine App mit den Home-APIs zu veröffentlichen. Für das Testen und Verwenden der Home-APIs ist sie nicht erforderlich.

Wenn eine App nicht in der Developer Console registriert ist, befindet sie sich im Status nicht bestätigt. Dies wird für das 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 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 der Developer Console). Alle Geräte in einer Struktur erhalten Zugriff.

Wenn eine App in der Developer Console und für den Zugriff auf einen oder mehrere Gerätetypen genehmigt wurde und die Marken bestätigung für OAuthabgeschlossen wurde, befindet sie sich im Status bestätigt. Dieser Status ist erforderlich, um eine App in der Produktion zu starten:

• Die Limits für Testnutzer gelten nicht mehr. Jeder Nutzer kann der App Berechtigungen erteilen.
• Der Nutzer kann nur Berechtigungen für die Gerätetypen erteilen, die in der Developer Consolegenehmigt 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, die Struktur auszuwählen, für die er der App Zugriff gewähren möchte.
   1. Bei einer nicht bestätigten App sind alle Gerätetypen, die von den Home-APIs unterstützt werden, für die App verfügbar.
   2. Bei einer bestätigten App kann der Nutzer nur Berechtigungen für die Gerätetypen erteilen, die in Developer Consolegenehmigt wurden.
   3. Bei sicherheits- oder datenschutzrelevanten Gerätetypen, die von der App verwaltet werden können, 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 mit den Home-APIs den Status der Geräte in der Struktur lesen und sie steuern. Wenn der Nutzer der App keine Berechtigung für einen bestimmten Gerätetyp oder ein sicherheits- oder datenschutzrelevantes Gerät erteilt, kann die App die Home-APIs nicht verwenden, um darauf zuzugreifen, es zu steuern oder automatisierte Abläufe zu erstellen.

Berechtigungen ändern

Wenn Sie die Berechtigung für den 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 der er wechseln möchte. Dabei wird dem Nutzer noch einmal der Zustimmungsbildschirm angezeigt, auch wenn er zuvor bereits seine Zustimmung erteilt hat.

Rufen Sie dazu requestPermissions() noch einmal auf und setzen Sie das Flag forceLaunch auf true:

homeManager.requestPermissions(forceLaunch=true)

Berechtigungen widerrufen

Nutzer können zuvor erteilte Berechtigungen widerrufen:

1. Über die Seite „Mein Konto“ von Google > Daten und Datenschutz > Drittanbieter-Apps und ‑Dienste. Dadurch wird das OAuth-Token widerrufen, das bei der ersten Zustimmung ausgestellt wurde, und der Zugriff auf alle Instanzen der App widerrufen, die der Nutzer auf allen Oberflächen (Smartphones) und in allen Strukturen verwendet hat.

   Der Nutzer kann über einen Deeplink zur Unterseite Drittanbieter-Apps und ‑Dienste weitergeleitet werden. Verwenden Sie dazu das folgende URL-Schema:

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

2. Über die GHA > Einstellungen > Verknüpfte Apps Seite. Wenn Sie in der GHA auf settings klicken, gelangen Sie zu der Seite Einstellungen. Klicken Sie dort auf die Kachel Verknüpfte Apps. Sie werden zu einer Seite weitergeleitet, die dem Zustimmungsbildschirm ähnelt. Auf dieser Seite kann der Nutzer den Zugriff auf die App entfernen. Auf derselben Seite kann der Nutzer auch ändern, auf welche Gerätetypen oder bestimmte sicherheits- oder datenschutzrelevante 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 oder eingeschränkten Gerätetypen wie Schlössern, Kameras oder Türklingeln müssen Nutzer die Berechtigung einzeln erteilen.

Verwenden Sie die Funktion consentedDeviceTypes() auf Strukturebene, um zu ermitteln, ob ein Nutzer die Berechtigung für den Zugriff auf einen sicherheits- oder datenschutzrelevanten 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 okGoogle Befehl ist ein Befehl auf Geräteebene und kann verwendet werden, um jedes Gerät in der Struktur zu automatisieren. Eine App, die die Home-APIs verwendet, hat jedoch möglicherweise nicht Zugriff auf alle Geräte. In der folgenden Tabelle wird beschrieben, wie Berechtigungen in solchen Fällen erzwungen werden.

Anleitung, wenn der Nutzer alle Berechtigungen widerruft

Wenn der Nutzer alle 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 vorherigen Daten entfernt werden, einschließlich aller in der Anwendung gespeicherten Daten.