Benachrichtigungen für Smart-Home-Aktionen

Mit Benachrichtigungen können Sie über Google Assistant Nutzer über wichtige gerätebezogene Ereignisse oder Änderungen informieren.smart home 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 eingeklemmt ist.

Mit Ihrer smart home-Aktion können Nutzern die folgenden Arten von Benachrichtigungen 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 haben die Möglichkeit, alle proaktiven Benachrichtigungen in der Google Home app (GHA) zu aktivieren oder zu deaktivieren.

Ereignisse, die Benachrichtigungen auslösen

Wenn Geräteereignisse auftreten, sendet die Action-Ausführung eine Benachrichtigungsanfrage an Google. Die Gerätemerkmale, die von Ihrer smart home-Aktion 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:

Eigenschaft Ereignisse
ObjectDetection Vom Gerät erkannte Objekte, z. B. wenn ein erkanntes Gesicht an der Tür erkannt wird. Beispiel: „Alice und Bob sind an der Haustür.“
RunCycle Das Gerät schließt einen Zyklus ab. Beispiel: „Der Waschmaschinenzyklus ist abgeschlossen.“
SensorState Das Gerät erkennt einen unterstützten Sensorstatus. Beispiel: „Der Rauchmelder hat Rauch festgestellt.“

Die folgenden Eigenschaften unterstützen Nachfragen:

Merkmal Ereignisse
LockUnlock Abschlussstatus und Status ändern sich nach Ausführung des Gerätebefehls action.devices.commands.LockUnlock. Beispiele: „Die Haustür ist verriegelt“ oder „Die Haustür klemmt.“
NetworkControl Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.TestNetworkSpeed. Beispiel: „Dein Netzwerkgeschwindigkeitstest ist abgeschlossen. Die Downloadgeschwindigkeit vom Router im Büro beträgt derzeit 80,2 Kbit/s und die Uploadgeschwindigkeit 9,3 Kbit/s.“
OpenClose Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.OpenClose. Beispiele: „Die Haustür wurde geöffnet“ oder „Die Haustür konnte nicht geöffnet werden.“

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

Benachrichtigungen für Ihre Smart-Home-Aktion erstellen

Sie können Ihrer smart home-Aktion in folgenden Phasen Benachrichtigungen hinzufügen:

  1. Teile Google mit, ob Benachrichtigungen von der 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 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 auch die Möglichkeit hinzufügen, dass Nutzer Benachrichtigungen explizit auf dem Gerät 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 tätigst, um 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 Option zum Aktivieren/Deaktivieren 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, wie Sie Ihre SYNC-Antwort festlegen:

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

Benachrichtigungsanfragen an Google senden

Um Benachrichtigungen auf der Assistant auszulösen, sendet dein 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:

Hinweis: Achten Sie bei diesen Schritten darauf, dass Sie das richtige GCP-Projekt verwenden. Dies ist das Projekt, das Ihrer smart home-Projekt-ID entspricht.
  1. Rufen Sie in der 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

Senden Sie die Benachrichtigungsanfrage mit der devices.reportStateAndNotification API. 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. Je nach Gerätemerkmal kann Ihr notifications-Objekt unterschiedliche Felder enthalten.

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

Nutzlast für proaktive Benachrichtigungen senden

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

HTTP

Die Home Graph API bietet einen HTTP-Endpunkt.

  1. Verwenden Sie die heruntergeladene JSON-Datei für das Dienstkonto, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen finden Sie unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem 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. Kombiniere die Report State- und die Benachrichtigungs-JSON und das Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier ein Beispiel für die Anfrage in der Befehlszeile mit curl als Test:
  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 stellt einen gRPC-Endpunkt bereit.

  1. Rufen Sie die Protocol Buffers-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 Node.js-Client für Google APIs bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit der ReportStateAndNotificationRequest auf. Sie gibt ein Promise mit der 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 bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie HomeGraphApiService mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit dem ReportStateAndNotificationRequest auf. Sie gibt ReportStateAndNotificationResponse zurück.
// 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 einer Folgeantwort 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 an alle Geräte des Nutzers.

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

HTTP

Die Home Graph API bietet einen HTTP-Endpunkt.

  1. Verwenden Sie die heruntergeladene JSON-Datei für das Dienstkonto, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen finden Sie unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem 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 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. Kombiniere die Report State- und die Benachrichtigungs-JSON und das Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier ein Beispiel für die Anfrage in der Befehlszeile mit curl als Test:
  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 stellt einen gRPC-Endpunkt bereit.

  1. Rufen Sie die Protocol Buffers-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 Node.js-Client für Google APIs bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den Dienst google.homegraph mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit der ReportStateAndNotificationRequest auf. Sie gibt ein Promise mit der 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 dem ReportStateAndNotificationRequest auf. Es gibt ein ReportStateAndNotificationResponse zurück.
// 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 Mit Cloud Logging auf Ereignislogs zugreifen beschrieben. Diese Protokolle sind nützlich, um die Qualität der Benachrichtigungen in Ihrer Aktion zu testen und aufrechtzuerhalten.

Das folgende Schema zeigt einen notificationLog-Eintrag:

Attribut Beschreibung
requestId ID der Benachrichtigungsanfrage.
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 Benachrichtigungsnutzlast hinweisen können. Einige davon sind möglicherweise nur für Aktionen verfügbar, die noch nicht in der Produktionsversion eingeführt 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 Property notificationSupportedByAgent des benachrichtigenden Geräts in SYNC auf „falsch“ gesetzt ist.
NOTIFICATION_ENABLED_BY_USER_FALSE Gibt an, dass der Nutzer Benachrichtigungen auf dem Gerät, das die Benachrichtigung sendet, in der GHA nicht 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/Gebäude zugewiesen hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht als Produktionsversion eingeführt wurden.

Zusätzlich zu 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).