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:
- 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. - 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
auftrue
. - Wenn der Nutzer Benachrichtigungen in der Geräte-App explizit deaktiviert hat, setze das Attribut
devices.notificationSupportedByAgent
auffalse
.
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
-
Rufen Sie in Google Cloud Console die Seite HomeGraph API auf.
Zur Seite „HomeGraph API“ - Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
- Klicken Sie auf AKTIVIEREN.
Dienstkontoschlüssel erstellen
Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:
-
Rufen Sie in Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.
Zur Seite Dienstkontoschlüssel erstellen - Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
- Geben Sie im Feld Dienstkontoname einen Namen ein.
- Geben Sie im Feld Dienstkonto-ID eine ID ein.
Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.
Wählen Sie als Schlüsseltyp die Option JSON aus.
- 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.
- 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.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich
https://www.googleapis.com/auth/homegraph
ab: - Erstellen Sie die JSON-Anfrage mit der
agentUserId
. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification: - 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:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
- Rufen Sie die Protokollpuffer-Dienstdefinition für die Home Graph API ab.
- Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
- Rufen Sie die Methode ReportStateAndNotification auf.
Node.js
Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie den
google.homegraph
-Dienst mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit ReportStateAndNotificationRequest auf. Sie gibt einenPromise
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.
- Initialisieren Sie
HomeGraphApiService
mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
auf. Es wird einReportStateAndNotificationResponse
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.
- 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.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich
https://www.googleapis.com/auth/homegraph
ab: - Erstellen Sie die JSON-Anfrage mit der
agentUserId
. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification: - 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:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
- Rufen Sie die Protokollpuffer-Dienstdefinition für die Home Graph API ab.
- Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
- Rufen Sie die Methode ReportStateAndNotification auf.
Node.js
Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie den
google.homegraph
-Dienst mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
reportStateAndNotification
mit ReportStateAndNotificationRequest auf. Sie gibt einenPromise
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.
HomeGraphApiService
mit Standardanmeldedaten für Anwendungen initialisieren- Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
auf. Es wird einReportStateAndNotificationResponse
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
).