Berechtigungs-API

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

Berechtigungen-API einbinden

Bevor Sie fortfahren, müssen Sie das Zuhause initialisieren. Die Instanz homeManager aus diesem Schritt wird in allen Beispielen für Berechtigungen verwendet.

Registrieren Sie zuerst eine ActivityResultCaller mit dem SDK. In der Beispielanwendung wird das so 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 seine Einwilligung erteilt hat. Rufen Sie dazu die Methode hasPermissions() der Home-Instanz auf, um einen Flow mit PermissionsState-Werten zu erhalten:

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 die Prüfung eine PermissionsState von NOT_GRANTED oder PERMISSIONS_STATE_UNAVAILABLE zurückgibt, müssen Sie Berechtigungen anfordern. Wenn die Prüfung eine PermissionsState von GRANTED zurückgibt, ein nachfolgender Aufruf von structures() aber keine Strukturen zurückgibt, hat der Nutzer den Zugriff auf die App über die Seite Google Home app (GHA)-Einstellungen widerrufen. Sie sollten dann Berechtigungen anfordern. Andernfalls sollte der Nutzer bereits Zugriff haben.

Berechtigungen anfordern

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

Wenn der Nutzer noch keine Berechtigungen erteilt hat, verwende die Methode requestPermissions() der Home-Instanz, um die Berechtigungsoberfläche zu öffnen 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 richtig gestartet werden kann, müssen Sie bereits OAuth für Ihre App eingerichtet haben.

Berechtigungen erteilen

Sie sollten jetzt Ihre App ausführen und Berechtigungen von einem Nutzer erhalten können. Welche Nutzer Berechtigungen gewähren können und für welche Gerätetypen Berechtigungen gewährt werden können, hängt davon ab, ob Sie Ihre App in der Google Home Developer Console registriert haben.

Eine Developer Console-Registrierung ist erforderlich, um eine App mit den Home APIs zu veröffentlichen. Es ist nicht erforderlich, 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 für den Test der Verwendung der Home APIs empfohlen:

• Nur Nutzer, die in der OAuth-Konsole als Testnutzer registriert sind, können Berechtigungen für die App gewähren. Für eine nicht bestätigte App ist die Anzahl der Testnutzer auf 100 beschränkt.

• Eine nicht bestätigte App hat Zugriff auf Geräte aller Gerätetypen, die von OAuth für die Smart-Home-APIs unterstützt werden (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 im 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, hat sie den Status verifiziert. 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 die Berechtigung erteilen.
• Der Nutzer kann die Berechtigung nur für die Gerätetypen gewähren, die in der Developer Console genehmigt wurden.

Nachdem OAuth eingerichtet ist, löst der Aufruf von requestPermissions() durch die App die folgenden Dialoge 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 von den Smart-Home-APIs unterstützten Gerätetypen für die App verfügbar.
   2. Bei einer überprüften App kann der Nutzer die Berechtigung nur den Gerätetypen gewähren, die in Developer Console genehmigt wurden.
   3. Bei sensiblen Gerätetypen, auf die die App Zugriff zur Verwaltung hat, kann der Nutzer den Zugriff pro Gerät einschränken. Wenn ein Nutzer beispielsweise drei Schlösser hat, kann er nur für eines dieser Schlösser Zugriff gewähren.

Sobald die Berechtigung erteilt wurde, kann die App den Status der Geräte im Gebäude über die Home APIs lesen und sie 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 gewähren möchten, können Sie die Kontoauswahl starten, 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 Einwilligungsbildschirm angezeigt, auch wenn er bereits zuvor seine Einwilligung erteilt hat.

Rufen Sie dazu requestPermissions() noch einmal auf, wobei das Flag forceLaunch auf true gesetzt ist:

homeManager.requestPermissions(forceLaunch=true)

Berechtigungen widerrufen

Nutzer können zuvor gewährten Zugriff widerrufen:

1. Über die Seite Google Konten > „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.

2. Über die Seite GHA > Einstellungen > Verknüpfte Apps Wenn Sie auf settings im Dreistrich-Menü GHA klicken, gelangen Sie zur Seite Einstellungen. Klicken Sie dort auf die Kachel Verknüpfte Apps. Daraufhin wird eine Seite geöffnet, die dem Einwilligungsbildschirm ähnelt. Auf dieser Seite kann der Nutzer den Zugriff auf die App entfernen. Außerdem kann er auf dieser Seite festlegen, welche Gerätetypen oder bestimmten sensiblen Geräte Zugriff auf die App haben.

3. Über die Seite „Verknüpfte Apps“ direkt im Web.

Berechtigungen für „Hey Google“

Der Befehl okGoogle gilt für die gesamte Struktur und kann verwendet werden, um jedes Gerät in der Struktur zu automatisieren. Eine Home APIs-App hat jedoch möglicherweise nicht auf jedes Gerät Zugriff. In der folgenden Tabelle wird beschrieben, wie Berechtigungen in solchen Fällen erzwungen werden.