Benachrichtigungen für Smart-Home-Aktionen

Benachrichtigungen ermöglichen es deiner Cloud-to-cloud-Integration, Google Assistant zu verwenden, um Nutzer über wichtige gerätebezogene Ereignisse oder Änderungen zu informieren. Du kannst Benachrichtigungen implementieren, um Nutzer über zeitnahe Geräteereignisse zu informieren, z. B. wenn jemand an der Tür ist, oder um über eine angeforderte Änderung des Gerätestatus zu berichten, z. B. wenn ein Türschloss erfolgreich verriegelt wurde oder klemmt.

Ihre Cloud-to-cloud-Integration kann die folgenden Arten von Benachrichtigungen an Nutzer senden:

• Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Geräteereignis benachrichtigt, ohne dass er zuvor eine Anfrage an seine Geräte gestellt hat, z. B. wenn es an der Tür klingelt.

• 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, deren Ausführung einige Zeit in Anspruch nimmt. Folgeantworten werden nur unterstützt, wenn Gerätebefehlsanfragen von Smart Speakern und Smart Displays gesendet werden.

Assistant stellt diese Benachrichtigungen Nutzern als Ansagen auf Smart Speakern 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

Wenn Geräteereignisse auftreten, sendet deine Auftragsausführung eine Benachrichtigungsanfrage an Google. Die von deiner Cloud-to-cloud-Integration unterstützten Geräteeigenschaften bestimmen, welche Arten von Benachrichtigungsereignissen verfügbar sind und welche Daten du in diese Benachrichtigungen aufnehmen kannst.

Die folgenden Attribute unterstützen proaktive Benachrichtigungen:

Die folgenden Eigenschaften unterstützen Folgeantworten:

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

Benachrichtigungen für Ihre Cloud-zu-Cloud-Integration erstellen

Fügen Sie Ihrer Cloud-to-cloud-Integration in den folgenden Phasen Benachrichtigungen hinzu:

1. Teile Google mit, ob Benachrichtigungen in 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 Änderung zu informieren.
2. Wenn ein relevantes Geräteereignis oder eine Statusänderung auftritt, die eine Benachrichtigung auslöst, sende eine Benachrichtigungsanfrage, indem du die Report State reportStateAndNotification API aufrufst. Wenn sich der Gerätestatus geändert hat, kannst du in deinem Report State- und Benachrichtigungsaufruf sowohl eine Status- als auch eine Benachrichtigungsnutzlast senden.

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

Geben Sie an, ob Benachrichtigungen in Ihrer App aktiviert sind

Nutzer können festlegen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie diese Funktion in der GHA aktivieren. In der App für dein smart home-Gerät kannst du optional auch die Möglichkeit hinzufügen, dass Nutzer Benachrichtigungen vom Gerät explizit aktivieren oder deaktivieren können, z. B. in den App-Einstellungen.

Teile Google mit, dass Benachrichtigungen für dein Gerät aktiviert sind, indem du einen Request SYNC-Aufruf ausführst, um die Gerätedaten zu aktualisieren. Du solltest immer eine SYNC-Anfrage wie diese senden, wenn Nutzer diese Einstellung in deiner App ändern.

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

• Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit aktiviert hat oder du keine Umschaltoption anbietest, setze die Property devices.notificationSupportedByAgent auf true.
• Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit deaktiviert hat, setze die Property devices.notificationSupportedByAgent auf false.

Das folgende Snippet zeigt ein Beispiel für die Einrichtung der SYNC-Antwort:

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

Benachrichtigungsanfragen an Google senden

Damit Benachrichtigungen auf dem Assistant ausgelöst werden, sendet deine Auftragsausführung über einen Report State- und Notification API-Aufruf eine Benachrichtigungsnutzlast an den Google Home Graph.

Google HomeGraph API aktivieren

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

   Zur HomeGraph API-Seite
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 über die Google Cloud Console zu generieren:

1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

   Zur Seite „Dienstkonten“

   Möglicherweise müssen Sie ein Projekt auswählen, bevor Sie zur Seite „Dienstkonten“ weitergeleitet werden.

2. Klicken Sie auf addDienstkonto erstellen.

3. Geben Sie im Feld Dienstkontoname einen Namen ein.

4. Geben Sie im Feld Dienstkonto-ID eine ID ein.

5. Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

6. Klicken Sie auf Erstellen und fortfahren.

7. Wählen Sie im Drop-down-Menü Rolle die Option Dienstkonten > Ersteller des OpenID Connect-Identitätstokens für das Dienstkonto aus.

8. Klicken Sie auf Weiter.

9. Klicken Sie auf Fertig.

10. Wählen Sie das gerade erstellte Dienstkonto aus der Liste der Dienstkonten aus und wählen Sie im Menü more_vert Aktionen die Option Schlüssel verwalten aus.

11. Wählen Sie Schlüssel hinzufügen > Neuen Schlüssel erstellen aus.

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

13. 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. Das ist eine eindeutige ID, die von Ihrer Plattform für das Ereignis generiert wird, das die Benachrichtigung auslöst. Die eventId sollte eine Zufallskennung sein, die sich bei jeder Benachrichtigungsanfrage ändert.

Fügen Sie im 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äteattribut unterschiedliche Felder enthalten.

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

• Nutzlast für proaktive Benachrichtigungen senden
• Nutzlast für Folgeantwort senden

Nutzlast für proaktive Benachrichtigungen senden

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

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
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 für eine Folgeantwort senden

Die Nutzlast für eine Folgeantwort enthält den Status der Anfrage, Fehlercodes für Ereignisfehler (falls zutreffend) und die gültige followUpToken, die während der Intent-Anfrage EXECUTE angegeben wurde. Die followUpToken muss innerhalb von fünf Minuten verwendet werden, damit sie gültig bleibt und die Antwort der ursprünglichen Anfrage richtig zugeordnet werden kann.

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

{
  "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 die followUpToken, um die Benachrichtigung nur auf dem Gerät auszugeben, mit dem der Nutzer ursprünglich interagiert hat, und nicht auf allen Geräten des Nutzers.

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

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,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 das Ereignis-Logging, wie unter Cloud-Logging für Cloud-zu-Cloud beschrieben. Diese Logs sind nützlich, um die Qualität der Benachrichtigungen in Ihrer Aktion zu testen und aufrechtzuerhalten.

Das folgende Schema zeigt einen notificationLog-Eintrag:

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

Beispiele für Status:

Zusätzlich zu diesen allgemeinen Status, die für alle Benachrichtigungen gelten können, kann das Feld status gegebenenfalls auch eigenschaftsspezifische Status enthalten (z. B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).