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.

Die Home APIs verwenden OAuth 2.0, um Zugriff auf Geräte im Gebäude zu gewähren. Mit OAuth können Nutzer einer App oder einem Dienst eine Berechtigung gewähren, ohne ihre Anmeldedaten preisgeben zu müssen. Mit der Berechtigungs-API kann der Nutzer über sein Google-Konto Home APIs-Apps Zugriff auf Geräte in seinem Zuhause gewähren.

Die Verwendung der Permissions API umfasst eine Reihe von Schritten in Ihrer App, in Google Cloud und in der Google Home Developer Console:

1. OAuth in Google Cloud einrichten
   1. App signieren
   2. OAuth-Zustimmungsbildschirm einrichten
   3. App registrieren und Anmeldedaten erstellen
2. Permissions API einbinden
   1. Berechtigungen prüfen
   2. Berechtigungen anfordern
3. Berechtigungen erteilen
   1. Berechtigungen ändern
   2. Berechtigungen widerrufen

OAuth in Google Cloud einrichten

Wenn Sie bereits einen bestätigten OAuth-Client haben, können Sie diesen verwenden, ohne einen neuen einzurichten. Weitere Informationen finden Sie unter Bestehender OAuth-Client.

App signieren

1. Generieren Sie einen OAuth-Schlüssel, indem Sie die App in Android Studio ausführen. Wenn Sie eine App in Android Studio ausführen oder beheben, wird automatisch ein OAuth-Schlüssel für die Entwicklung und Fehlerbehebung generiert. Eine vollständige Erklärung finden Sie unter Android Studio: Debug-Build signieren.

   Verbinden Sie Ihr Mobilgerät mit Ihrem lokalen Computer. Auf Android Studio werden Ihre verbundenen Geräte nach Modellnummer aufgeführt. Wählen Sie Ihr Gerät aus der Liste aus und klicken Sie dann auf Projekt ausführen. Dadurch wird die Beispiel-App erstellt und auf Ihrem Mobilgerät installiert.

   Eine ausführliche Anleitung finden Sie auf der Website für Android-Entwickler unter Apps auf einem Hardwaregerät ausführen.

   Beenden Sie jetzt die laufende App.

2. Rufen Sie den SHA-1-Fingerabdruck des OAuth-Zertifikats ab. Folgen Sie dazu der Anleitung unter OAuth 2.0 einrichten / Native Anwendungen / Android auf der Hilfeseite der Google Cloud Console.

OAuth-Zustimmungsbildschirm einrichten

1. Rufen Sie in der Google Cloud Console das Dashboard für die Projektauswahl auf und wählen Sie das Projekt aus, mit dem Sie OAuth-Anmeldedaten erstellen möchten.
2. Rufen Sie die Seite APIs und Dienste auf und klicken Sie im Navigationsmenü auf Anmeldedaten.

3. Wenn Sie den Einwilligungsbildschirm für dieses Google Cloud-Projekt noch nicht konfiguriert haben, wird die Schaltfläche Zustimmungsbildschirm konfigurieren angezeigt. Konfigurieren Sie in diesem Fall den Zustimmungsbildschirm mithilfe der folgenden Schritte. Fahren Sie andernfalls mit dem nächsten Abschnitt fort.

   1. Klicken Sie auf Zustimmungsbildschirm konfigurieren. Die Seite OAuth-Zustimmungsbildschirm wird angezeigt.
   2. Wählen Sie je nach Anwendungsfall Intern oder Extern aus und klicken Sie dann auf Erstellen. Der Bereich OAuth-Zustimmungsbildschirm wird angezeigt.
   3. Geben Sie auf der Seite mit den App-Informationen die Informationen gemäß der Anleitung auf dem Bildschirm ein und klicken Sie dann auf Speichern und fortfahren. Der Bereich Bereiche wird angezeigt.
   4. Sie müssen keine Bereiche hinzufügen. Klicken Sie daher auf Speichern und fortfahren. Der Bereich Testnutzer wird angezeigt.
   5. Wenn Sie Nutzer hinzufügen möchten, um den Zugriff auf Ihre App zu testen, klicken Sie auf Nutzer hinzufügen. Der Bereich Nutzer hinzufügen wird angezeigt. Testnutzer haben die Berechtigung, Berechtigungen in Ihrer App zu gewähren.
   6. Fügen Sie im leeren Feld eine oder mehrere E-Mail-Adressen von Google-Konten hinzu und klicken Sie dann auf Hinzufügen.
   7. Klicken Sie auf Speichern und fortfahren. Der Bereich Summary (Zusammenfassung) wird angezeigt.
   8. Überprüfen Sie die Informationen auf dem OAuth-Zustimmungsbildschirm und klicken Sie dann auf Zurück zum Dashboard.

Ausführliche Informationen finden Sie in der Google Cloud Console-Hilfe unter OAuth-Zustimmungsbildschirm einrichten.

App registrieren und Anmeldedaten erstellen

Wenn Sie die App für OAuth 2.0 registrieren und OAuth-Anmeldedaten erstellen möchten, folgen Sie der Anleitung unter OAuth 2.0 einrichten. Sie müssen den App-Typ angeben, also native/Android-App.

Fügen Sie den SHA-1-Fingerabdruck, den Sie beim Signieren der App erhalten haben, dem OAuth-Client hinzu, den Sie in der Google Cloud Console eingerichtet haben. Folgen Sie dazu der Anleitung unter OAuth 2.0-/native Anwendungen einrichten auf der Hilfeseite der Google Cloud Console.

Wenn Ihr Mobilgerät mit Ihrem lokalen Computer verbunden ist, wählen Sie es in der Liste aus und klicken Sie noch einmal auf Projekt ausführen, um es auszuführen. Eine ausführlichere Anleitung finden Sie auf der Website für Android-Entwickler unter Apps auf einem Hardwaregerät ausführen.

Berechtigungen-API einbinden

Nutzer müssen Ihrer App Berechtigungen erteilen, um auf Geräte in einem bestimmten Gebäude zugreifen zu können. Prüfen Sie zuerst, ob Sie die Home APIs initialisiert haben. Die Instanz homeManager aus diesem Schritt wird in allen Beispielen für Berechtigungen hier 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 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 Sie Zugriff auf die Registrierungsfunktion der Console benötigen, wenden Sie sich an Ihren Google-Technical Account Manager (TAM).

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.

Wenn Sie bereits einen OAuth-Client haben

Wenn Sie bereits einen bestätigten OAuth-Client für eine veröffentlichte App haben, können Sie diesen OAuth-Client verwenden, um die Home APIs zu testen.

Die Registrierung von Developer Console ist nicht erforderlich, um die Home APIs zu testen und zu verwenden. Sie benötigen jedoch weiterhin eine genehmigte Developer Console-Registrierung, um Ihre App zu veröffentlichen, auch wenn Sie einen bestätigten OAuth-Client aus einer anderen Integration haben.

Dabei gilt Folgendes:

• Bei der Verwendung eines vorhandenen OAuth-Clients ist die Anzahl der Nutzer auf 100 beschränkt. Informationen zum Hinzufügen von Testnutzern finden Sie unter OAuth-Zustimmungsbildschirm einrichten. Unabhängig von der OAuth-Bestätigung gilt für Home APIs eine Beschränkung auf 100 Nutzer, die Ihrer Anwendung Berechtigungen gewähren können. Diese Einschränkung wird aufgehoben, sobald die Developer Console-Registrierung abgeschlossen ist.

• DieDeveloper Console Registrierung sollte zur Genehmigung gesendet werden, wenn Sie bereit sind, die Berechtigungen für Gerätetypen über OAuth einzuschränken, um Ihre App mit den Smart-Home-APIs zu aktualisieren.

Bei Google Cloud Apps, für die die OAuth-Überprüfung noch aussteht, können Nutzer den OAuth-Ablauf erst abschließen, wenn die Überprüfung abgeschlossen ist. Versuche, Berechtigungen zu gewähren, schlagen mit folgendem Fehler fehl:

Access blocked: <Project Name> has not completed the Google verification process.

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.