Durch Benachrichtigungen kann deine smart home-Aktion Google Assistant verwenden, um Nutzer über wichtige gerätebezogene Ereignisse oder Änderungen zu informieren. Sie können Benachrichtigungen implementieren, um Nutzer über Geräteereignisse zu informieren, 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 einrastet oder klemmt.
Die Aktion smart home kann folgende Arten von Benachrichtigungen an Nutzer senden:
Proaktive Benachrichtigungen: Der Nutzer wird über ein smart home-Geräteereignis ohne vorherige Nutzeranfragen an seine Geräte benachrichtigt, z. B. die 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 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 auf intelligenten 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, wird beim Ausführen der Aktion 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.
Bei den folgenden Merkmalen werden proaktive Benachrichtigungen unterstützt:
Eigenschaft | Veranstaltungen |
---|---|
ObjectDetection | Objekte, die vom Gerät erkannt werden, 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 Waschgang der Waschmaschine ist abgeschlossen." |
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 aktiviert einen Voralarm mit einem Countdown beim Betreten, der durch eine offene Tür ausgelöst wird. |
CameraStream | Link zum Livestream der Kamera, nachdem ein Objekt oder eine Bewegung vom Gerät erkannt wurde. |
MotionDetection | „Am 1. Juli 2020 um 12 Uhr wurde Bewegung erkannt.“ |
Die folgenden Eigenschaften unterstützen Folgeantworten:
Eigenschaft | Veranstaltungen |
---|---|
ArmDisarm | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.ArmDisarm . Beispiel: „Das Sicherheitssystem wurde scharf geschaltet.“
|
LockUnlock | Abschlussstatus und Statusänderung 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.“
|
StartStop | Abschlussstatus und Statusänderung nach Ausführung des Gerätebefehls action.devices.commands.StartStop . Beispiel: "Der Staubsauger wurde gestartet."
|
Alle Gerätetypen unterstützen Benachrichtigungen für die jeweiligen Traits.
Benachrichtigungen für deine Smart-Home-Aktion erstellen
Füge deiner smart home-Aktion in den folgenden Phasen Benachrichtigungen hinzu:
- 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. - Wenn ein relevantes Geräteereignis oder eine relevante Statusänderung auftritt, die eine Benachrichtigung auslöst, kannst du durch Aufrufen der Report State
reportStateAndNotification
API eine Benachrichtigungsanfrage senden. 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 ausführlicher beschrieben.
Angeben, ob Benachrichtigungen in deiner App aktiviert sind
Nutzer können auswählen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie dieses Feature in der GHA aktivieren. In der App für dein smart home-Gerät kannst du optional auch die Möglichkeit für Nutzer hinzufügen, Benachrichtigungen auf dem Gerät explizit ein-/auszuschalten, z. B. über die 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 SYNC
-Anfrage wie diese immer dann senden, wenn Nutzer diese Einstellung in Ihrer Anwendung ä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 Ein/Aus-Schaltfläche zur Verfügung stellst, setze das Attribut
devices.notificationSupportedByAgent
auftrue
. - Wenn der Nutzer Benachrichtigungen in deiner Geräte-App explizit deaktiviert hat, setze das Attribut
devices.notificationSupportedByAgent
auffalse
.
Das folgende Snippet zeigt ein Beispiel, 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 den Notification API-Aufruf eine Benachrichtigungsnutzlast an die Google Home Graph.
Google HomeGraph API aktivieren
-
Rufen Sie in der 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 der 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-Token aus.
Wählen Sie als Schlüsseltyp die Option JSON aus.
- Klicken Sie auf Erstellen. Es wird dann eine JSON-Datei mit Ihrem Schlüssel auf Ihren Computer heruntergeladen.
Benachrichtigung senden
Senden Sie die Benachrichtigungsanfrage mit der devices.reportStateAndNotification
API.
Ihre JSON-Anfrage muss eine eventId
enthalten. Dies 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 jedes Mal ändert, wenn Sie eine Benachrichtigungsanfrage senden.
Fügen Sie in das notifications
-Objekt, das Sie im API-Aufruf übergeben, einen priority
-Wert ein, der definiert, wie die Benachrichtigung dargestellt werden soll. Dein 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 eine Option auf einem der folgenden Tabs aus, um die API aufzurufen:
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 finden Sie unter Authentifizierung mit einem Dienstkonto.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich
https://www.googleapis.com/auth/homegraph
ab: - Erstellen Sie die JSON-Anfrage mit
agentUserId
. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification: - Kombiniere Report State und Notification JSON und das Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Das folgende Beispiel zeigt, wie Sie die Anfrage in der Befehlszeile mit
curl
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 stellt einen gRPC-Endpunkt bereit.
- Rufen Sie die Protokollzwischenspeicher-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 einPromise
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 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. Sie gibtReportStateAndNotificationResponse
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 für eine nachfolgende Antwort enthält den Status der Anfrage, gegebenenfalls Fehlercodes für Ereignisfehler und die gültige followUpToken
, die während der EXECUTE
-Intent-Anfrage angegeben wird. Die followUpToken
muss innerhalb von fünf Minuten verwendet werden, um gültig zu bleiben 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 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 eine Option auf einem der folgenden Tabs aus, um die API aufzurufen:
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 finden Sie unter Authentifizierung mit einem Dienstkonto.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich
https://www.googleapis.com/auth/homegraph
ab: - Erstellen Sie die JSON-Anfrage mit
agentUserId
. Hier sehen Sie eine JSON-Beispielanfrage für Report State und Notification: - Kombiniere Report State und Notification JSON und das Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Das folgende Beispiel zeigt, wie Sie die Anfrage in der Befehlszeile mit
curl
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 stellt einen gRPC-Endpunkt bereit.
- Rufen Sie die Protokollzwischenspeicher-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 einPromise
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.
HomeGraphApiService
mit den Standardanmeldedaten für Anwendungen initialisieren- Rufen Sie die Methode
reportStateAndNotification
mitReportStateAndNotificationRequest
auf. Sie gibt eineReportStateAndNotificationResponse
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 Logs sind nützlich, um die Qualität von Benachrichtigungen in deiner Aktion zu testen und aufrechtzuerhalten.
Hier das Schema eines notificationLog
-Eintrags:
Attribut | Beschreibung |
---|---|
requestId |
Benachrichtigungsanfrage-ID. |
structName |
Name der Benachrichtigungsstruktur, z. B. "ObjectDetection". |
status |
Zeigt 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 Produktion gestartet 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 Geräts, über das eine Benachrichtigung gesendet wird, falsch ist.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Gibt an, dass der Nutzer auf dem Benachrichtigungsgerät in GHA keine Benachrichtigungen aktiviert hat. Dieser Status ist nur für Aktionen verfügbar, die noch nicht als Produktionsversion 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 charakterspezifische Statuswerte enthalten (z.B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).