Powiadomienia umożliwiają aplikacji smart home Action korzystanie z funkcji Google Assistant, aby informować użytkowników o ważnych zdarzeniach lub zmianach związanych z urządzeniem. Możesz wdrażać powiadomienia, aby powiadamiać użytkowników o zdarzeniach związanych z urządzeniem, na przykład gdy ktoś stoi przy drzwiach, lub aby zgłaszać żądaną zmianę stanu urządzenia, na przykład gdy zamek w drzwiach został zablokowany lub zablokował się.
Akcja smart home może wysyłać do użytkowników te typy powiadomień:
Aktywne powiadomienia: informuje użytkownika o zdarzeniu urządzenia smart home bez wcześniejszego wysyłania do niego próśb od użytkownika, np. o dzwonienie dzwonka.
Odpowiedzi na żądanie: potwierdzenie, że żądanie polecenia urządzenia zostało wykonane lub nie, na przykład w przypadku zamykania drzwi. Używaj tych alertów w przypadku poleceń dotyczących urządzenia, które wymagają czasu na wykonanie. Odpowiedzi na dalsze pytania są obsługiwane tylko wtedy, gdy żądania poleceń są wysyłane z inteligentnych głośników i inteligentnych ekranów.
Assistant wyświetla użytkownikom te powiadomienia w formie ogłoszeń na inteligentnych głośnikach i ekranach. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia w Google Home app (GHA).
Zdarzenia wyzwalające powiadomienia
W przypadku wystąpienia zdarzeń na urządzeniu usługa Realizacja akcji wysyła do Google prośbę o powiadomienie. Cechy urządzenia obsługiwane przez Twoje działanie smart home określają, jakie typy zdarzeń powiadomienia są dostępne i jakie dane można uwzględnić w tych powiadomieniach.
Te cechy obsługują powiadomienia proaktywne:
Cecha | Wydarzenia |
---|---|
ObjectDetection | Obiekty wykryte przez urządzenie, na przykład w przypadku wykrycia rozpoznanej twarzy przy drzwiach. Na przykład: "Alicja i Robert są przy drzwiach wejściowych." |
RunCycle | Urządzenie kończy cykl. Przykład: "Cykl pralki został zakończony." |
SensorState | Urządzenie wykrywa stan obsługiwanego czujnika. Na przykład: "Czujnik dymu wykrył dym." |
Te cechy obsługują odpowiedzi uzupełniające:
Cecha | Wydarzenia |
---|---|
LockUnlock | stan po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock . Na przykład: "Zamek w drzwiach wejściowych został zamknięty" lub "Drzwi wejściowe są zablokowane".
|
NetworkControl | Stan ukończenia i stan zmienią się po wykonaniu polecenia na urządzeniu action.devices.commands.TestNetworkSpeed . Na przykład: „Test szybkości sieci już się zakończył. Szybkość pobierania na routerze w biurze to obecnie 80,2 kb/s, a szybkość wysyłania – 9,3 kb/s."
|
OpenClose | stan po wykonaniu polecenia urządzenia action.devices.commands.OpenClose . Na przykład: "Drzwi wejściowe są otwarte" lub "Nie udało się otworzyć drzwi wejściowych".
|
Wszystkie typy urządzeń obsługują powiadomienia dotyczące odpowiednich cech.
Tworzenie powiadomień dla inteligentnego domu
Dodawanie powiadomień do działania smart home na tych etapach:
- Powiadom Google, czy powiadomienia są włączone w aplikacji na urządzeniusmart home. Jeśli użytkownicy włączą lub wyłączą powiadomienia w aplikacji, wyślij
SYNC
, aby powiadomić Google o zmianie urządzenia. - Gdy wystąpi odpowiednie zdarzenie lub zmiana stanu urządzenia, która powoduje wysłanie powiadomienia, wyślij żądanie powiadomienia, wywołując interfejs API Report State
reportStateAndNotification
. Jeśli stan urządzenia uległ zmianie, możesz wysłać zarówno stan, jak i dane powiadomienia w wywołaniu Report State i powiadomieniu.
W kolejnych sekcjach znajdziesz bardziej szczegółowe informacje o tych czynnościach.
Określ, czy powiadomienia są włączone w aplikacji
Użytkownicy mogą zdecydować, czy chcą otrzymywać proaktywne powiadomienia, włączając tę funkcję w sekcji GHA. W aplikacji na urządzeniesmart home możesz też opcjonalnie dodać możliwość włączania i wyłączania powiadomień na urządzeniu, na przykład w ustawieniach aplikacji.
Aby poinformować Google, że powiadomienia są włączone na urządzeniu, wywołaj polecenie Request SYNC (Prośba o SYNCHRONIZACJĘ) w celu zaktualizowania danych na urządzeniu. Wysyłaj takie żądanie SYNC
za każdym razem, gdy użytkownicy zmienią to ustawienie w Twojej aplikacji.
W odpowiedzi na SYNC
prześlij jedną z tych informacji:
- Jeśli użytkownik samodzielnie włączył powiadomienia w aplikacji na urządzeniu lub jeśli nie oferujesz 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 wywołać powiadomienia w Assistant, usługa zapewniająca realizację wysyła do usługi Google Home Graph ładunek powiadomienia za pomocą wywołania interfejsu Report State i Notification API.
Włącz interfejs Google HomeGraph API
-
W sekcji Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API - Wybierz projekt, który odpowiada Twojemu identyfikatorowi projektu smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z poziomu Google Cloud Console, wykonaj te czynności:
-
W panelu Google Cloud Console otwórz stronę Utwórz klucz konta usługi.
Otwórz stronę tworzenia klucza konta usługi - Na liście Konto usługi wybierz Nowe konto usługi.
- W polu Nazwa konta usługi wpisz nazwę.
- W polu Identyfikator konta usługi wpisz identyfikator.
Na liście Rola wybierz Konta usługi > Twórca tokena konta usługi.
W polu Typ klucza wybierz opcję JSON.
- Kliknij Utwórz. Plik JSON z kluczem zostanie pobrany na komputer.
Wysyłanie powiadomienia
Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification
.
Żądanie JSON musi zawierać eventId
, czyli unikalny identyfikator generowany przez Twoją platformę dla zdarzenia wywołującego powiadomienie. Wartość eventId
powinna być losowym identyfikatorem, który jest inny za każdym razem, gdy wysyłasz żądanie powiadomienia.
W obiekcie notifications
, który przekazujesz w wywołaniu interfejsu API, dołącz wartość priority
, która określa sposób wyświetlania powiadomienia. Obiekt notifications
może zawierać różne pola w zależności od urządzenia.
Aby ustawić ładunek i wywołać interfejs API, wykonaj jedną z tych czynności:
Wysyłanie aktywnego powiadomienia
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs API Home Graph 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 artykule Uwierzytelnianie za pomocą konta usługi.
- Aby uzyskać token dostępu OAuth 2.0 z zakresem
https://www.googleapis.com/auth/homegraph
, użyj polecenia oauth2l: - Utwórz żądanie JSON za pomocą
agentUserId
. Oto przykładowa prośba JSON dotycząca Report State i powiadomienia: - Połącz dane Report State i JSON powiadomienia oraz token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład wykonania żądania w wierszu poleceń przy użyciu interfejsu
curl
w ramach testu:
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 udostępnia punkt końcowy gRPC
- Pobierz definicję usługi protocol buffers interfejsu API Home Graph.
- Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować atrapy klienta w jednym z obsługiwanych języków.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsów API Google zapewnia powiązania dla interfejsu Home Graph API.
- Inicjuje usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z parametrem ReportStateAndNotificationRequest. ZwracaPromise
z ReportStateAndNotificationResponse.
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 HomeGraph API dla języka Java udostępnia powiązania dla interfejsu API Home Graph.
- Inicjuj
HomeGraphApiService
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z parametremReportStateAndNotificationRequest
. ZwracaReportStateAndNotificationResponse
.
// 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);
Wysyłanie danych odpowiedzi na prośbę o dodatkowe informacje
Ładunek kolejnej odpowiedzi zawiera stan żądania, kody błędów dotyczące nieudanych zdarzeń (w stosownych przypadkach) oraz prawidłowy followUpToken
podany w żądaniu intencji EXECUTE
. Aby followUpToken
pozostało ważne i odpowiednio powiązane z pierwotnym żądaniem, musisz użyć go w ciągu 5 minut.
Ten fragment kodu przedstawia 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 followUpToken
, aby wyświetlać powiadomienie tylko na urządzeniu, z którym użytkownik pierwotnie się komunikował, a nie na wszystkich urządzeniach użytkownika.
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs API Home Graph udostępnia punkt końcowy HTTP.
- Użyj pobranego pliku JSON konta usługi, aby utworzyć token internetowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie za pomocą konta usługi.
- Aby uzyskać token dostępu OAuth 2.0 z zakresem
https://www.googleapis.com/auth/homegraph
, użyj polecenia oauth2l: - Utwórz żądanie JSON za pomocą
agentUserId
. Oto przykładowa prośba JSON dotycząca Report State i powiadomienia: - Połącz dane Report State i JSON powiadomienia oraz token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład wykonania żądania w wierszu poleceń przy użyciu interfejsu
curl
w ramach testu:
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 udostępnia punkt końcowy gRPC.
- Pobierz definicję usługi protocol buffers interfejsu API Home Graph.
- Aby wygenerować atrapy klienta w jednym z obsługiwanych języków, postępuj zgodnie z instrukcjami podanymi w dokumentacji dla deweloperów gRPC.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsów API Google zapewnia powiązania dla interfejsu Home Graph API.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z parametrem ReportStateAndNotificationRequest. ZwracaPromise
z ReportStateAndNotificationResponse.
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 HomeGraph API dla języka Java udostępnia powiązania dla interfejsu API Home Graph.
- Inicjuj
HomeGraphApiService
za pomocą domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
z parametremReportStateAndNotificationRequest
. 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);
Logowanie
Powiadomienia obsługują rejestrowanie zdarzeń zgodnie z opisem w artykule Uzyskiwanie dostępu do dzienników zdarzeń za pomocą Cloud Logging. Te dzienniki są przydatne do testowania i utrzymywania jakości powiadomień w Twoim widżecie.
Oto schemat wpisu notificationLog
:
Właściwość | Opis |
---|---|
requestId |
Identyfikator prośby dotyczącej powiadomienia. |
structName |
Nazwa struktury powiadomienia, np. „ObjectDetection”. |
status |
Wskazuje stan powiadomienia. |
Pole status
zawiera różne stany, które mogą wskazywać na błędy w ładunku powiadomienia. Niektóre z nich mogą być dostępne tylko w przypadku działań, które nie zostały jeszcze wdrożone w wersji produkcyjnej.
Przykładowe stany:
Stan | Opis |
---|---|
EVENT_ID_MISSING |
Oznacza, ż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 wysyłającego powiadomienie podana w elementach SYNC ma wartość false (fałsz).
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu wysyłającym powiadomienia w ramach GHA. Ten stan jest dostępny tylko w przypadku działań, które nie zostały wdrożone w wersji produkcyjnej. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Wskazuje, że użytkownik nie przypisał urządzenia wysyłającego powiadomienia do domu lub budynku. Ten stan jest dostępny tylko w przypadku działań, które nie zostały wdrożone w wersji produkcyjnej. |
Oprócz tych ogólnych stanów, które mogą dotyczyć wszystkich powiadomień, pole status
może zawierać stany specyficzne dla cech (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).