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 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 ein Gebäude erstellen, falls noch keines 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 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 das Gebäude 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 das Gebäude. Wenn die Prüfung den Wert PermissionsState für GRANTED zurückgibt, ein nachfolgender Aufruf von structures() aber keine Gebäude 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 Gebäude und Geräte in einem bestimmten Gebäude 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. 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. Dies wird für Tests 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 einem Gebäude 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 OAuth abgeschlossen 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, das Gebäude auszuwählen, für das 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 die App verwalten kann, 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 im Gebäude 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 einem anderen Gebäude erteilen möchten, kann die Kontoauswahl gestartet werden, damit der Nutzer das Google-Konto und das Gebäude auswählen kann, zu dem er wechseln möchte. Dabei wird dem Nutzer noch einmal der Zustimmungsbildschirm angezeigt, auch wenn die Einwilligung bereits erteilt wurde.

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

homeManager.requestPermissions(forceLaunch=true)

Berechtigungen mit Gebäudehinweis ändern

Mit dem Gebäudehinweis 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 Home-APIs-Berechtigungen des Nutzers angefordert wird. Wenn Sie Gebäudeparameter in die Autorisierungsanfrage einfügen, wird das Berechtigungsdialogfeld automatisch auf das ausgewählte Gebäude fokussiert. So werden Probleme für den Nutzer reduziert und Konfigurationsfehler vermieden.

Der Gebäudehinweis wird mit der ConsentScreenOptions Datenklasse verwaltet. Die Klasse ConsentScreenOptions akzeptiert die folgenden Konfigurationsparameter:

• structureId : Die spezifische Gebäude-ID, die im Berechtigungsdialogfeld vorab ausgewählt werden soll. Rufen Sie diese ab, indem Sie die Gebäude eigenschaften für das Gebäude prüfen, das aktualisiert wird.
• allowedStructureIds : Eine Liste von Gebäude-IDs. Wenn angegeben, werden im Berechtigungsdialogfeld die verfügbaren Gebäude so gefiltert, dass nur die in dieser Liste angezeigt werden. In den meisten Fällen kann dies nicht angegeben werden, es sei denn, Sie möchten sicherstellen, dass der Nutzer in einer bereits gewährten Liste von Gebäuden bleibt.
• allowStructureChange : Bestimmt, ob der Nutzer das vorab ausgewählte Gebäude ändern darf. Setzen Sie dies in den meisten Fällen auf true, wenn mindestens eine der Optionen allowedStructureIds und structureId angegeben ist, um das natürliche Verhalten des Nutzers zu unterstützen.

Übergeben Sie dieses Objekt als optionalen Parameter im Aufruf requestPermissions() und setzen Sie das Flag forceLaunch auf true:

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)

Der Zustimmungsbildschirm wird dem Nutzer bereits nach dem Gebäude gefiltert angezeigt, das im Objekt ConsentScreenOptions angegeben ist.

Nutzer mit Gebäudehinweis Gebäude wechseln lassen

Wenn ein Nutzer mehrere Gebäude in einer App hat und Sie eines vorab auswählen möchten, ihm aber trotzdem erlauben möchten, zwischen den verfügbaren Gebäuden zu wechseln, aktivieren Sie Gebäudeänderungen mit dem Flag allowStructureChange und geben Sie eine Liste der Gebäude 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“ von Google > Daten und Datenschutz > Drittanbieter-Apps und ‑Dienste. Dadurch wird das OAuth-Token widerrufen, das bei der ersten Einwilligung ausgestellt wurde, und 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 mit einem 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 Gebäudeebene, 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
            }
        }
    }
}

OkGoogle-Berechtigungen

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