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 mit seinem Google-Konto Apps Zugriff auf Geräte in seinem Zuhause gewähren.

Berechtigungen-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 Berechtigungsbeispielen hier 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 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 ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      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")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Wenn bei der Prüfung PermissionsState von NOT_GRANTED oder PERMISSIONS_STATE_UNAVAILABLE zurückgegeben wird, müssen Sie Berechtigungen anfordern. Wenn bei der Prüfung ein PermissionsState von GRANTED zurückgegeben wird, ein nachfolgender Aufruf von structures() aber keine Strukturen zurückgibt, hat der Nutzer den Zugriff auf die App über die Einstellungsseite Google Home app (GHA) widerrufen. Sie sollten dann Berechtigungen anfordern. Andernfalls sollte der Nutzer bereits Zugriff haben.

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 wird, müssen Sie OAuth für Ihre App eingerichtet haben.

Berechtigungen erteilen

Sie sollten Ihre App jetzt 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 verifiziert. 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 finden Sie unter Developer Console). Alle Geräte in einer Struktur 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 Markenbestä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 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() in der 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 Gebäude auszuwählen, auf das die App Zugriff erhalten 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 auf Gerätebasis einschränken. Wenn ein Nutzer beispielsweise drei Schlösser hat, kann er nur den 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 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 ursprünglichen Einwilligung ausgestellt wurde, und der Zugriff auf alle Instanzen der App, die der Nutzer auf allen Oberflächen (Smartphones) und 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 Einwilligungsbildschirm ä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.

„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.