Benachrichtigungen für Smart-Home-Aktionen

Mithilfe von Benachrichtigungen kann deine smart home-Aktion Nutzer über Google Assistant über wichtige gerätebezogene Ereignisse oder Änderungen informieren. Sie können Benachrichtigungen implementieren, um Nutzer auf zeitnahe Geräteereignisse aufmerksam zu machen, z. B. wenn jemand an der Tür ist, oder um eine angeforderte Änderung des Gerätestatus zu melden, z. B. wenn ein Türschloss erfolgreich geschlossen wurde oder klemmt.

Die Aktion smart home kann die folgenden Arten von Benachrichtigungen an Nutzer senden:

  • Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Geräteereignis benachrichtigt, ohne vorher eine Nutzeranfrage an seine Geräte gesendet zu haben, z. B. das Klingeln der Türklingel.

  • Folgeantworten: Eine Bestätigung, dass eine Gerätebefehlsanfrage erfolgreich war oder fehlgeschlagen ist, z. B. beim Verriegeln einer Tür. Verwenden Sie diese Benachrichtigungen für Gerätebefehle, die einige Zeit in Anspruch nehmen. Folgeantworten werden nur unterstützt, wenn Gerätebefehlsanfragen von intelligenten Lautsprechern und Smart Displays gesendet werden.

Assistant stellt Nutzern diese Benachrichtigungen als Ankündigungen auf intelligenten Lautsprechern und Smart Displays zur Verfügung. Proaktive Benachrichtigungen sind standardmäßig deaktiviert. Nutzer können alle proaktiven Benachrichtigungen über die Google Home app (GHA) aktivieren oder deaktivieren.

Ereignisse, die Benachrichtigungen auslösen

Bei Geräteereignissen wird vom Fulfillment-Team eine Benachrichtigungsanfrage an Google gesendet. Die von Ihrer smart home-Aktion unterstützten Geräte-Traits bestimmen, welche Arten von Benachrichtigungsereignissen verfügbar sind und welche Daten Sie in diese Benachrichtigungen aufnehmen können.

Die folgenden Eigenschaften unterstützen proaktive Benachrichtigungen:

Wesenszug Veranstaltungen
ObjectDetection Objekte, die vom Gerät erkannt werden, z. B. wenn ein erkanntes Gesicht an der Tür erkannt wird Beispiel: „Anne und Bob sind an der Haustür.“
RunCycle Das Gerät schließt einen Zyklus ab. Beispiel: "Der Waschgang der Waschmaschine ist beendet."
SensorState Das Gerät erkennt einen unterstützten Sensorstatus. Beispiel: „Der Rauchmelder hat Rauch erkannt.“
TemperatureControl Das Gerät erreicht einen Temperatursollwert. Beispiel: "Der Ofen wurde auf 350 Grad vorgeheizt."
ArmDisarm Das System startet einen Voralarmstatus mit einem Countdown beim Betreten, der durch eine offene Tür ausgelöst wird.
CameraStream Link zum Livestream der Kamera, nachdem das Gerät ein Objekt oder eine Bewegung erkannt hat.
MotionDetection „Am 1. Juli 2020 wurde um 12 Uhr Bewegung erkannt.“

Die folgenden Eigenschaften unterstützen Folgeantworten:

Wesenszug Veranstaltungen
ArmDisarm Abschlussstatus und -status ändern sich nach Ausführung des action.devices.commands.ArmDisarm-Gerätebefehls. Beispiel: „Das Sicherheitssystem wurde scharf geschaltet.“
LockUnlock Abschlussstatus und -status ändern sich nach Ausführung des action.devices.commands.LockUnlock-Gerätebefehls. Beispiele: Die Haustür wurde verriegelt oder Die Haustür klemmt.
NetworkControl Abschlussstatus und -status ändern sich nach Ausführung des action.devices.commands.TestNetworkSpeed-Gerätebefehls. Beispiel: „Der Test der Netzwerkgeschwindigkeit ist abgeschlossen. Die Downloadgeschwindigkeit des Routers im Büro beträgt derzeit 80,2 kbit/s und die Uploadgeschwindigkeit 9,3 kbit/s.“
OpenClose Abschlussstatus und -status ändern sich nach Ausführung des action.devices.commands.OpenClose-Gerätebefehls. Beispiele: „Die Haustür wurde geöffnet“ oder „Die Haustür konnte nicht geöffnet werden.“
StartStop Abschlussstatus und -status ändern sich nach Ausführung des action.devices.commands.StartStop-Gerätebefehls. Beispiel: „Der Staubsauger wurde gestartet.“

Alle Gerätetypen unterstützen Benachrichtigungen für die entsprechenden Traits.

Benachrichtigungen für deine Smart-Home-Aktion erstellen

Fügen Sie Ihrer smart home-Aktion in folgenden Phasen Benachrichtigungen hinzu:

  1. Du kannst Google mitteilen, ob Benachrichtigungen von deiner smart home-Geräte-App aktiviert sind. Wenn Nutzer Benachrichtigungen in deiner App aktivieren oder deaktivieren, sende eine SYNC-Anfrage, um Google über die Geräteänderung zu informieren.
  2. Wenn ein relevantes Geräteereignis oder eine relevante Statusänderung auftritt, das eine Benachrichtigung auslöst, senden Sie eine Benachrichtigungsanfrage, indem Sie die Report State reportStateAndNotification API aufrufen. Wenn sich der Gerätestatus geändert hat, können Sie sowohl den Status als auch die Benachrichtigungsnutzlast zusammen in Ihrem Report State- und Benachrichtigungsaufruf senden.

In den folgenden Abschnitten werden diese Schritte ausführlicher beschrieben.

Angeben, ob Benachrichtigungen in Ihrer App aktiviert sind

Nutzer können auswählen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie diese Funktion in GHA aktivieren. In der App für Ihr smart home-Gerät können Sie auch optional die Möglichkeit für Nutzer hinzufügen, Benachrichtigungen des Geräts explizit umschalten zu können, z. B. über Ihre App-Einstellungen.

Wenn Sie Google mitteilen möchten, dass Benachrichtigungen für Ihr Gerät aktiviert sind, führen Sie einen Request SYNC-Aufruf aus, um die Gerätedaten zu aktualisieren. Sie sollten eine SYNC-Anfrage wie diese senden, wenn Nutzer diese Einstellung in Ihrer Anwendung ändern.

Senden Sie in Ihrer SYNC-Antwort eine der folgenden Aktualisierungen:

  • Wenn der Nutzer Benachrichtigungen in Ihrer Geräte-App explizit aktiviert hat oder Sie keine Ein-/Aus-Schaltfläche sehen, setzen Sie das Attribut devices.notificationSupportedByAgent auf true.
  • Wenn der Nutzer Benachrichtigungen in der Geräte-App explizit deaktiviert hat, setze das Attribut devices.notificationSupportedByAgent auf false.

Das folgende Snippet zeigt ein Beispiel dafür, wie Sie Ihre SYNC-Antwort festlegen:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Benachrichtigungsanfragen an Google senden

Zum Auslösen von Benachrichtigungen im Assistant sendet die Auftragsausführung über einen Report State- und Notification API-Aufruf eine Benachrichtigungsnutzlast an Google Home Graph.

Google HomeGraph API aktivieren

  1. Rufen Sie in Google Cloud Console die Seite HomeGraph API auf.

    Zur Seite „HomeGraph API“
  2. Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
  3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:

Hinweis: Achten Sie darauf, dass Sie das richtige GCP-Projekt verwenden, wenn Sie diese Schritte ausführen. Dies ist das Projekt, das Ihrer smart home-Projekt-ID entspricht.
  1. Rufen Sie in Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.

    Zur Seite Dienstkontoschlüssel erstellen
  2. Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
  3. Geben Sie im Feld Dienstkontoname einen Namen ein.
  4. Geben Sie im Feld Dienstkonto-ID eine ID ein.
  5. Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.

  6. Wählen Sie als Schlüsseltyp die Option JSON aus.

  7. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

Benachrichtigung senden

Führen Sie den Aufruf der Benachrichtigungsanfrage mit der devices.reportStateAndNotification API aus. Ihre JSON-Anfrage muss eine eventId enthalten. Dabei handelt es sich um eine eindeutige ID, die von Ihrer Plattform für das Ereignis generiert wird, das die Benachrichtigung auslöst. eventId sollte eine zufällige ID sein, die sich jedes Mal unterscheidet, wenn Sie eine Benachrichtigungsanfrage senden.

Fügen Sie in das notifications-Objekt, das Sie in Ihrem API-Aufruf übergeben, einen priority-Wert ein, der definiert, wie die Benachrichtigung dargestellt werden soll. Das notifications-Objekt kann je nach Geräteeigenschaft unterschiedliche Felder enthalten.

Folgen Sie einem der folgenden Pfade, um die Nutzlast festzulegen und die API aufzurufen:

Proaktive Benachrichtigungsnutzlast senden

Wählen Sie zum Aufrufen der API auf einem der folgenden Tabs eine Option aus:

HTTP

Die Home Graph API stellt einen HTTP-Endpunkt bereit.

  1. Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen findest du unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich https://www.googleapis.com/auth/homegraph ab:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Erstellen Sie die JSON-Anfrage mit der agentUserId. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "ObjectDetection": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
    
  6. Kombinieren Sie Report State und Notification JSON sowie das Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier sehen Sie ein Beispiel dafür, wie Sie die Anfrage mit curl in der Befehlszeile als Test stellen:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Die Home Graph API bietet einen gRPC-Endpunkt

  1. Rufen Sie die Protokollpuffer-Dienstdefinition für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.

  1. Initialisieren Sie den google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Sie gibt einen Promise mit ReportStateAndNotificationResponse zurück.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

Java

Die HomeGraph API-Clientbibliothek für Java enthält Bindungen für die Home Graph API.

  1. Initialisieren Sie HomeGraphApiService mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse zurückgegeben.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    
Nutzlast der Folgeantwort senden

Die Nutzlast für eine Folgeantwort enthält den Status der Anfrage, ggf. Fehlercodes für Ereignisfehler und die gültige followUpToken, die während der EXECUTE-Intent-Anfrage angegeben wurde. followUpToken muss innerhalb von fünf Minuten verwendet werden, um seine Gültigkeit zu behalten und die Antwort ordnungsgemäß der ursprünglichen Anfrage zuzuordnen.

Das folgende Snippet zeigt ein Beispiel für eine EXECUTE-Anfragenutzlast mit dem Feld followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google verwendet followUpToken, um die Benachrichtigung nur auf dem Gerät auszugeben, mit dem der Nutzer ursprünglich interagiert hat, und nicht an alle Geräte des Nutzers gesendet.

Wählen Sie zum Aufrufen der API auf einem der folgenden Tabs eine Option aus:

HTTP

Die Home Graph API stellt einen HTTP-Endpunkt bereit.

  1. Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen findest du unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich https://www.googleapis.com/auth/homegraph ab:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Erstellen Sie die JSON-Anfrage mit der agentUserId. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "NetworkControl": {
                "priority": 0,
                "followUpResponse": {
                  "status": "SUCCESS",
                  "followUpToken": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. Kombinieren Sie Report State und Notification JSON sowie das Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier sehen Sie ein Beispiel dafür, wie Sie die Anfrage mit curl in der Befehlszeile als Test stellen:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Die Home Graph API bietet einen gRPC-Endpunkt

  1. Rufen Sie die Protokollpuffer-Dienstdefinition für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.

  1. Initialisieren Sie den google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Sie gibt einen Promise mit ReportStateAndNotificationResponse zurück.
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

Java

Die HomeGraph API-Clientbibliothek für Java enthält Bindungen für die Home Graph API.

  1. HomeGraphApiService mit Standardanmeldedaten für Anwendungen initialisieren
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse zurückgegeben.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

Logging

Benachrichtigungen unterstützen die Ereignisprotokollierung, wie unter Auf Ereignisprotokolle mit Cloud Logging zugreifen beschrieben. Diese Logs sind nützlich, um die Benachrichtigungsqualität innerhalb deiner Aktion zu testen und aufrechtzuerhalten.

Hier das Schema eines notificationLog-Eintrags:

Property Beschreibung
requestId Benachrichtigungsanfrage-ID.
structName Name der Benachrichtigungsstruktur, z. B. "ObjectDetection".
status Gibt den Status der Benachrichtigung an.

Das Feld status enthält verschiedene Status, die auf Fehler in der Nutzlast der Benachrichtigung hinweisen können. Einige davon sind möglicherweise nur für Aktionen verfügbar, die noch nicht in der Produktion veröffentlicht wurden.

Beispiele für Status:

Status Beschreibung
EVENT_ID_MISSING Gibt an, dass das erforderliche Feld eventId fehlt.
PRIORITY_MISSING Gibt an, dass ein priority-Feld fehlt.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Gibt an, dass die in SYNC angegebene Eigenschaft notificationSupportedByAgent des benachrichtigenden Geräts auf „false“ gesetzt ist.
NOTIFICATION_ENABLED_BY_USER_FALSE Gibt an, dass der Nutzer keine Benachrichtigungen auf dem Benachrichtigungsgerät in GHA aktiviert hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht in der Produktion eingeführt wurden.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Gibt an, dass der Nutzer das benachrichtigende Gerät keinem Zuhause bzw. Gebäude zugewiesen hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht in der Produktion eingeführt wurden.

Neben diesen allgemeinen Status, die für alle Benachrichtigungen gelten können, kann das Feld status gegebenenfalls auch merkmalsspezifische Status enthalten (z.B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).