Benachrichtigungen für Smart-Home-Aktionen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Mit Benachrichtigungen können Sie über Ihre Cloud-to-cloud-Integration Google Assistant verwenden, um Nutzer über wichtige gerätebezogene Ereignisse oder Änderungen zu informieren. Sie können Benachrichtigungen implementieren, um Nutzer zeitnah über Geräteereignisse zu informieren, z. B. wenn jemand vor der Tür steht, oder um über eine angeforderte Gerätestatusänderung zu berichten, z. B. wenn ein Schlossriegel erfolgreich eingerastet oder klemmt.

Über Ihre Cloud-to-cloud-Integration können Nutzern die folgenden Benachrichtigungstypen gesendet werden:

• Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Gerätereignis informiert, ohne dass er zuvor eine Anfrage an sein Gerät gesendet hat, z. B. wenn die Türklingel 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, die einige Zeit in Anspruch nehmen. Folgeantworten werden nur unterstützt, wenn Gerätebefehlsanfragen von intelligenten Lautsprechern und Smart Displays gesendet werden.

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

Ereignisse, die Benachrichtigungen auslösen

Wenn Geräteereignisse auftreten, sendet Ihr Dienstleister eine Benachrichtigungsanfrage an Google. Die Gerätemerkmale, die von Ihrer Cloud-to-cloud-Integration unterstützt werden, bestimmen, welche Arten von Benachrichtigungsereignissen verfügbar sind und welche Daten Sie in diese Benachrichtigungen aufnehmen können.

Die folgenden Merkmale unterstützen proaktive Benachrichtigungen:

Die folgenden Eigenschaften unterstützen Nachfragen:

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

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

Sie können Benachrichtigungen in folgenden Phasen Ihrer Cloud-to-cloud-Integration hinzufügen:

1. Teilen Sie Google mit, ob Benachrichtigungen über Ihre smart home-Geräte-App aktiviert sind. Wenn Nutzer Benachrichtigungen in Ihrer App aktivieren oder deaktivieren, senden Sie eine SYNC-Anfrage, um Google über die Geräteänderung zu informieren.
2. Wenn ein relevantes Geräteereignis oder eine Zustandsänderung eintritt, die eine Benachrichtigung auslöst, senden Sie eine Benachrichtigungsanfrage, indem Sie die Report State reportStateAndNotification API aufrufen. Wenn sich der Gerätestatus geändert hat, kannst du sowohl einen Status als auch eine Benachrichtigungsnutzlast zusammen in deinem Report State- und Benachrichtigungsaufruf senden.

In den folgenden Abschnitten werden diese Schritte näher erläutert.

Angeben, ob Benachrichtigungen in Ihrer App aktiviert sind

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

Informiere Google, dass Benachrichtigungen für dein Gerät aktiviert sind, indem du einen Request SYNC-Aufruf ausführst, um die Gerätedaten zu aktualisieren. Sie sollten eine solche SYNC-Anfrage senden, wenn Nutzer diese Einstellung in Ihrer App ä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 anbieten, legen Sie für das Attribut devices.notificationSupportedByAgent den Wert true fest.
• Wenn der Nutzer Benachrichtigungen in Ihrer Geräte-App ausdrücklich deaktiviert hat, legen Sie für die Property devices.notificationSupportedByAgent den Wert false fest.

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

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

Benachrichtigungsanfragen an Google senden

Um Benachrichtigungen auf der Assistant auszulösen, sendet Ihr Fulfillment-System über einen Report State- und Notification API-Aufruf eine Benachrichtigungsnutzlast an die Google Home Graph.

Google HomeGraph API aktivieren

1. Rufen Sie in der 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

So generieren Sie einen Dienstkontoschlüssel aus der Google Cloud Console:

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

   Rufen Sie die Seite „Dienstkonten“ auf.

   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 von OpenID Connect-Identitätstokens für Dienstkonten aus.

8. Klicken Sie auf Weiter.

9. Klicken Sie auf Fertig.

10. Wählen Sie in der Liste der Dienstkonten das gerade erstellte Dienstkonto und dann 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. Es wird dann eine JSON-Datei mit Ihrem Schlüssel auf Ihren Computer heruntergeladen.

Benachrichtigung senden

Rufe die Benachrichtigungsanfrage mit der devices.reportStateAndNotification API auf. 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 Zufalls-ID sein, die sich jedes Mal unterscheidet, wenn Sie eine Benachrichtigungsanfrage senden.

Fügen Sie dem notifications-Objekt, das Sie in Ihrem API-Aufruf übergeben, einen priority-Wert hinzu, der festlegt, wie die Benachrichtigung angezeigt werden soll. Das notifications-Objekt kann je nach Gerätemerkmal unterschiedliche Felder enthalten.

Führen Sie einen der folgenden Pfade aus, um die Nutzlast festzulegen und die API aufzurufen:

• Nutzlast für proaktive Benachrichtigungen senden
• Nutzlast für die Antwort 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 die Antwort senden

Die Nutzlast einer Folgeantwort enthält den Status der Anfrage, gegebenenfalls Fehlercodes für Ereignisfehler und den gültigen followUpToken, der bei der EXECUTE-Intentanfrage angegeben wurde. Die followUpToken muss innerhalb von fünf Minuten verwendet werden, damit sie gültig bleibt und die Antwort richtig mit der ursprünglichen Anfrage verknüpft werden kann.

Das folgende Snippet zeigt eine Beispielnutzlast für eine EXECUTE-Anfrage 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 die Ereignisprotokollierung, wie in Cloud Logging für Cloud-zu-Cloud-Migrationen 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:

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