Benachrichtigungen für Smart-Home-Aktionen

Mit Benachrichtigungen kann 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 ü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ürriegel erfolgreich eingerastet ist oder sich verklemmt hat.

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 Anfragen an seine Geräte gesendet hat, z. B. wenn die Türklingel klingelt.

• Folgeantworten: Eine Bestätigung, dass eine Anfrage für einen Gerätebefehl erfolgreich war oder fehlgeschlagen ist, z. B. beim Verriegeln einer Tür. Verwende diese Benachrichtigungen für Gerätebefehle, deren Ausführung 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 Ankündigungen auf Smart Speakern und Smart Displays zur Verfügung. Proaktive Benachrichtigungen sind standardmäßig deaktiviert. Nutzer können alle proaktiven Benachrichtigungen über das Google Home app (GHA) aktivieren oder deaktivieren.

Ereignisse, die Benachrichtigungen auslösen

Wenn Geräteereignisse auftreten, sendet Ihre Auftragsausführung eine Benachrichtigungsanfrage an Google. Die Geräteattribute, 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 Eigenschaften unterstützen proaktive Benachrichtigungen:

Die folgenden Eigenschaften unterstützen Folgeantworten:

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

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

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

1. Teilen Sie Google mit, ob Benachrichtigungen in der App für Ihr smart home-Gerät 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 relevante 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, können Sie sowohl eine Status- als auch eine Benachrichtigungsnutzlast zusammen in Ihrem Report State- und Benachrichtigungsaufruf senden.

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

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 dein smart home-Gerät kannst du optional auch die Möglichkeit hinzufügen, dass Nutzer Benachrichtigungen vom Gerät aus explizit aktivieren oder deaktivieren können, z. B. über die App-Einstellungen.

Teilen Sie Google mit, dass Benachrichtigungen für Ihr Gerät aktiviert sind, indem Sie einen Request SYNC-Aufruf ausführen, um die Gerätedaten zu aktualisieren. Sie sollten eine SYNC-Anfrage wie diese immer dann senden, wenn Nutzer diese Einstellung in Ihrer App ändern.

Senden Sie in Ihrer SYNC-Antwort eines der folgenden Updates:

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

Das folgende Snippet zeigt ein Beispiel dafür, wie du deine SYNC-Antwort festlegst:

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

Benachrichtigungsanfragen an Google senden

Damit Benachrichtigungen auf dem Assistant ausgelöst werden, sendet dein Fulfillment-System über einen Report State- und Notification API-Aufruf eine Benachrichtigungsnutzlast an das 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

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 von OpenID Connect-Identitätstokens für Dienstkonten 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ü Aktionen more_vert 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 Benachrichtigungsanfrageaufruf 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 zufällige ID sein, die sich bei jeder Benachrichtigungsanfrage ändert.

Fügen Sie dem notifications-Objekt, das Sie in Ihrem API-Aufruf übergeben, einen priority-Wert hinzu, der definiert, wie die Benachrichtigung präsentiert werden soll. Ihr notifications-Objekt kann je nach Geräteattribut unterschiedliche Felder enthalten.

Gehen Sie einen der folgenden Wege, um die Nutzlast festzulegen und die API aufzurufen:

• Proaktive Benachrichtigungs-Payload senden
• Nutzlast für Folgeantwort senden

Proaktive Benachrichtigungs-Payload senden

Wählen Sie eine Option auf einem dieser Tabs aus, um die API aufzurufen:

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

Follow-up-Antwortnutzlast senden

Die Nutzlast für eine Follow-up-Antwort enthält den Status der Anfrage, gegebenenfalls Fehlercodes für Ereignisfehler und das gültige followUpToken, das während der EXECUTE-Intent-Anfrage angegeben wurde. Das followUpToken muss innerhalb von fünf Minuten verwendet werden, damit es 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 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 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 eine Option auf einem dieser Tabs aus, um die API aufzurufen:

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 gemäß Cloud Logging für Cloud-to-Cloud. Diese Logs sind nützlich, um die Qualität von Benachrichtigungen in Ihrer Action zu testen und zu optimieren.

Das folgende Schema zeigt einen notificationLog-Eintrag:

Das Feld status enthält verschiedene Status, die auf Fehler in der Benachrichtigungsnutzlast hinweisen können. Einige dieser Funktionen sind möglicherweise nur für Actions 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).