Dzięki powiadomieniom akcja smart home może używać Google Assistant do informowania użytkowników o ważnych zdarzeniach lub zmianach związanych z urządzeniem. Możesz zaimplementować powiadomienia, które będą powiadamiać użytkowników o odpowiednich zdarzeniach związanych z urządzeniem, na przykład gdy ktoś jest pod drzwiami, lub zgłaszać żądane zmiany stanu urządzenia, np. zatrzaśnięcie zamka zamka lub zablokowanie go.
Akcja smart home może wysyłać do użytkowników te typy powiadomień:
Powiadomienia proaktywne: powiadamia użytkownika o zdarzeniu na urządzeniu smart home, ale nie wysyła do urządzeń żadnych wcześniejszych żądań, np. dzwonka do drzwi.
Dalsze odpowiedzi: potwierdzenie, że żądanie polecenia urządzenia zostało zrealizowane lub nieudane, np. podczas zamykania drzwi. Używaj tych alertów w przypadku poleceń urządzenia, których wykonanie wymaga czasu. Dalsze odpowiedzi są obsługiwane tylko w przypadku żądań poleceń urządzenia wysyłanych z inteligentnych głośników i inteligentnych ekranów.
Assistant wysyła te powiadomienia użytkownikom w formie ogłoszeń na inteligentnych głośnikach i inteligentnych ekranach. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia na stronie Google Home app (GHA).
Zdarzenia wywołujące powiadomienia
Gdy wystąpi zdarzenie związane z urządzeniem, realizacja akcji wysyła do Google prośbę o powiadomienie. Cechy urządzenia obsługiwane przez akcję smart home określają, jakie typy zdarzeń powiadomień są dostępne i jakie dane można uwzględniać w tych powiadomieniach.
Te cechy obsługują aktywne powiadomienia:
Cecha | Wydarzenia |
---|---|
ObjectDetection | obiektów wykrytych przez urządzenie, np. rozpoznania twarzy za drzwiami. Na przykład: „Alicja i Robert są przy drzwiach wejściowych”. |
RunCycle | Urządzenie kończy cykl. Na przykład: „Zakończył się cykl prania”. |
SensorState | Urządzenie wykryło obsługiwany stan czujnika. Na przykład: „Czujnik dymu wykrył dym”. |
TemperatureControl | Urządzenie osiąga nastawę temperatury. Na przykład: „piekarnik został podgrzany do 350 stopni”. |
ArmDisarm | System przechodzi w stan przed alarmem i włącza odliczanie po otwarciu drzwi. |
CameraStream | Link do transmisji na żywo z kamery po wykryciu obiektu lub ruchu przez urządzenie. |
MotionDetection | „Wykryto ruch o 12:00 1 lipca 2020 r.” |
Te cechy zachęcają do udzielenia odpowiedzi:
Cecha | Wydarzenia |
---|---|
ArmDisarm | Zmiana stanu ukończenia i stanu po wykonaniu polecenia urządzenia action.devices.commands.ArmDisarm . Na przykład: „System alarmowy został włączony”.
|
LockUnlock | Zmiana stanu ukończenia i stanu po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock . Na przykład: „Drzwi wejściowe zostały zamknięte na zamek” lub „Zacięły się drzwi wejściowe”.
|
NetworkControl | Zmiana stanu ukończenia i stanu po wykonaniu polecenia urządzenia action.devices.commands.TestNetworkSpeed . Na przykład: „Test szybkości sieci się zakończył. Szybkość pobierania na routerze w biurze to obecnie 80,2 kb/s, a przesyłanie – 9,3 kb/s."
|
OpenClose | Zmiana stanu ukończenia i stanu po wykonaniu polecenia urządzenia action.devices.commands.OpenClose . Na przykład: „Otwarto drzwi wejściowe” lub „Nie udało się otworzyć drzwi wejściowych”.
|
StartStop | Zmiana stanu ukończenia i stanu po wykonaniu polecenia urządzenia action.devices.commands.StartStop . Na przykład: „Uruchomił się odkurzacz”.
|
Wszystkie typy urządzeń obsługują powiadomienia dotyczące odpowiednich cech.
Twórz powiadomienia dotyczące akcji w inteligentnym domu
Dodaj powiadomienia do akcji (smart home) na tych etapach:
- Wskaż Google, czy powiadomienia są włączone w aplikacji na urządzeniu smart home. Jeśli użytkownicy włączą lub wyłączą powiadomienia w aplikacji, wyślij prośbę
SYNC
, aby poinformować Google o zmianie urządzenia. - Gdy nastąpi odpowiednie zdarzenie lub zmiana stanu urządzenia, które wyzwala powiadomienie, wyślij żądanie powiadomienia, wywołując interfejs API Report State
reportStateAndNotification
. Jeśli stan urządzenia się zmieni, możesz wysłać razem ładunek stanu oraz ładunek powiadomienia w usłudze Report State i wywołaniu powiadomienia.
Poniżej znajdziesz bardziej szczegółowe informacje o tych czynnościach.
Określanie, czy powiadomienia są włączone w aplikacji
Użytkownicy mogą zdecydować, czy chcą otrzymywać aktywne powiadomienia, włączając tę funkcję na stronie GHA. W aplikacji na urządzeniu z systemem smart home możesz też opcjonalnie dodać możliwość jednoznacznego przełączania powiadomień z urządzenia, np. w ustawieniach aplikacji.
Poinstruuj Google, że na urządzeniu są włączone powiadomienia, wysyłając żądanie Poproś o SYNCHRONIZACJĘ, aby zaktualizować dane urządzenia. Takie żądanie SYNC
należy wysyłać za każdym razem, gdy użytkownicy zmienią to ustawienie w aplikacji.
W odpowiedzi na żądanie SYNC
wyślij jedną z tych informacji:
- Jeśli użytkownik jawnie włączył powiadomienia w aplikacji na urządzeniu lub jeśli nie ma opcji przełączania, ustaw właściwość
devices.notificationSupportedByAgent
natrue
. - Jeśli użytkownik wyraźnie wyłączył powiadomienia w aplikacji na urządzeniu, ustaw właściwość
devices.notificationSupportedByAgent
nafalse
.
Ten fragment kodu pokazuje, jak ustawić odpowiedź SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Wysyłaj prośby o powiadomienia do Google
Aby aktywować powiadomienia na platformie Assistant, realizacja wysyła ładunek powiadomień do interfejsu Google Home Graph za pomocą wywołania Report State i interfejsu Notification API.
Włącz interfejs Google HomeGraph API
-
W Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API - Wybierz projekt pasujący do identyfikatora projektu w smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z Google Cloud Console, wykonaj te czynności:
-
W sekcji Google Cloud Console otwórz stronę Tworzenie klucza konta usługi.
Otwórz stronę Tworzenie klucza konta usługi - Z listy Konto usługi wybierz Nowe konto usługi.
- W polu Nazwa konta usługi wpisz nazwę.
- W polu Identyfikator konta usługi wpisz identyfikator.
Z listy Rola wybierz Konta usługi > Twórca tokenów konta usługi.
W polu Typ klucza wybierz opcję JSON.
- Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na Twój komputer.
Wyślij powiadomienie
Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification
.
Żądanie JSON musi zawierać eventId
, czyli unikalny identyfikator generowany przez Twoją platformę dla zdarzenia aktywującego powiadomienie. eventId
powinien być losowym identyfikatorem, który jest inny za każdym razem, gdy wysyłasz żądanie powiadomienia.
W obiekcie notifications
przekazywanym w wywołaniu interfejsu API umieść wartość priority
określającą sposób wyświetlania powiadomienia. Obiekt notifications
może zawierać różne pola w zależności od właściwości urządzenia.
Użyj jednej z tych ścieżek, aby ustawić ładunek i wywołać interfejs API:
Wysyłanie ładunku z powiadomieniami
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API udostępnia punkt końcowy HTTP.
- Użyj pobranego pliku JSON konta usługi, aby utworzyć token sieciowy JSON (JWT). Więcej informacji znajdziesz w sekcji Uwierzytelnianie za pomocą konta usługi.
- Uzyskaj token dostępu OAuth 2.0 z zakresem
https://www.googleapis.com/auth/homegraph
za pomocą oauth2l: - Utwórz żądanie JSON z atrybutem
agentUserId
. Oto przykładowe żądanie JSON dla Report State i powiadomienia: - Połącz Report State, plik JSON powiadomień i token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak w ramach testu wysłać żądanie w wierszu poleceń za pomocą polecenia
curl
:
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
Interfejs API Home Graph zapewnia punkt końcowy gRPC
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndPowiadom.
Node.js
Klient Node.js interfejsów API Google dostarcza powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z metodą ReportStateAndmentRequest. Zwraca wartośćPromise
z parametrem ReportStateAndmentResponse.
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
Biblioteka klienta interfejsu API HomeGraph dla języka Java zawiera powiązania dla interfejsu API Home Graph.
- Zainicjuj
HomeGraphApiService
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metodyReportStateAndNotificationRequest
. Zwraca wartośćReportStateAndNotificationResponse
.
// 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);
Wyślij ładunek odpowiedzi
Ładunek na kolejną odpowiedź zawiera stan żądania, kody błędów błędów zdarzeń (w stosownych przypadkach) i prawidłowy followUpToken
podany w żądaniu intencji EXECUTE
. Aby zachować ważność i prawidłowo powiązać odpowiedź z pierwotnym żądaniem, trzeba użyć polecenia followUpToken
w ciągu 5 minut.
Poniżej znajdziesz przykładowy ładunek żądania EXECUTE
z polem 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 używa pola followUpToken
do wyświetlania powiadomienia tylko na urządzeniu, z którym użytkownik wszedł w interakcję, a nie na wszystkie urządzenia użytkownika.
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API udostępnia punkt końcowy HTTP.
- Użyj pobranego pliku JSON konta usługi, aby utworzyć token sieciowy JSON (JWT). Więcej informacji znajdziesz w sekcji Uwierzytelnianie za pomocą konta usługi.
- Uzyskaj token dostępu OAuth 2.0 z zakresem
https://www.googleapis.com/auth/homegraph
za pomocą oauth2l: - Utwórz żądanie JSON z atrybutem
agentUserId
. Oto przykładowe żądanie JSON dla Report State i powiadomienia: - Połącz Report State, plik JSON powiadomień i token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak w ramach testu wysłać żądanie w wierszu poleceń za pomocą polecenia
curl
:
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
Interfejs API Home Graph zapewnia punkt końcowy gRPC
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndPowiadom.
Node.js
Klient Node.js interfejsów API Google dostarcza powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z metodą ReportStateAndmentRequest. Zwraca wartośćPromise
z parametrem ReportStateAndmentResponse.
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
Biblioteka klienta interfejsu API HomeGraph dla języka Java zawiera powiązania dla interfejsu API Home Graph.
- Zainicjuj
HomeGraphApiService
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metodyReportStateAndNotificationRequest
. Zwraca wartośćReportStateAndNotificationResponse
// 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
Powiadomienia obsługują rejestrowanie zdarzeń zgodnie z opisem w sekcji Uzyskiwanie dostępu do dzienników zdarzeń za pomocą Cloud Logging. Te logi przydają się do testowania i utrzymywania jakości powiadomień w akcji.
Oto schemat wpisu notificationLog
:
Właściwość | Opis |
---|---|
requestId |
Identyfikator prośby o powiadomienie. |
structName |
Nazwa struktury powiadomienia, na przykład „ObjectDetection”. |
status |
Wskazuje stan powiadomienia. |
Pole status
zawiera różne stany, które mogą wskazywać na błędy w ładunku powiadomień. Niektóre z nich mogą być dostępne tylko w przypadku akcji, które nie zostały jeszcze wdrożone w wersji produkcyjnej.
Przykładowe stany:
Stan | Opis |
---|---|
EVENT_ID_MISSING |
Wskazuje, że brakuje wymaganego pola eventId .
|
PRIORITY_MISSING |
Wskazuje, że brakuje pola priority .
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Wskazuje, że właściwość notificationSupportedByAgent urządzenia powiadamiającego podana w zasadzie SYNC ma wartość fałsz.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu wysyłającym powiadomienie w: GHA. Ten stan jest dostępny tylko w przypadku akcji, które nie zostały jeszcze wdrożone w wersji produkcyjnej. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Wskazuje, że użytkownik nie przypisał urządzenia powiadamiającego do domu/domu. Ten stan jest dostępny tylko w przypadku akcji, które nie zostały jeszcze wdrożone w wersji produkcyjnej. |
Oprócz tych stanów ogólnych, które mają zastosowanie do wszystkich powiadomień, pole status
może też w razie potrzeby zawierać stany związane z cechą (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).