Dzięki powiadomieniom działanie smart home może korzystać z Google Assistant, aby informować użytkowników o ważnych zdarzeniach lub zmianach dotyczących urządzenia. Możesz skonfigurować powiadomienia, aby na bieżąco informować użytkowników o zdarzeniach związanych z urządzeniem, na przykład o tym, że ktoś jest przy drzwiach, lub o żądaniu zmiany stanu urządzenia, na przykład informacji o tym, że zamek w samochodzie został zablokowany lub się zaciął.
Akcja smart home może wysyłać do użytkowników te rodzaje powiadomień:
Aktywne powiadomienia: powiadamia użytkownika o zdarzeniu związanym z urządzeniem smart home bez wcześniejszego wysyłania do niego żądań, takich jak dzwonek.
Dalsze odpowiedzi: potwierdzenie, że polecenie urządzenia zakończyło się powodzeniem lub niepowodzeniem, na przykład zamknięcie drzwi. Używaj tych alertów do wykonywania poleceń na urządzeniu, którego wykonanie zajmuje dużo czasu.
Assistant wysyła do użytkowników te powiadomienia 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 z Google Home app (GHA).
Zdarzenia, które powodują wyświetlanie powiadomień
W chwili wystąpienia zdarzeń na urządzeniu Realizacja działania wysyła powiadomienie do Google. Cechy urządzenia obsługiwane przez działanie smart home określają, jakie typy zdarzeń powiadomień są dostępne i jakie dane mogą być zawarte w tych powiadomieniach.
Usługi te mają proaktywne powiadomienia:
Kasa | Zdarzenia |
---|---|
Wykrywanie obiektów | Obiekty wykryte przez urządzenie, na przykład wykryte przez drzwi. Na przykład: „Alicja i Robert są przed drzwiami”. |
RunCycle | Urządzenie kończy cykl. Na przykład: „Cykl pralki zakończył się”. |
Stan czujnika | Urządzenie wykrywa obsługiwany stan czujnika. Na przykład: „Czujnik dymu wykrył dym”. |
Sterowanie temperaturą | Urządzenie osiągnie nastawę temperatury. Na przykład: „piekarnik został podgrzany do 350 stopni”. |
AlarDisarm | System przechodzi w stan wstępnego alarmu z odliczaniem wejściowym, które jest aktywowane przez otwarte drzwi. |
Transmisja z kamery | Link do transmisji na żywo z kamery po wykryciu przez urządzenie obiektu lub ruchu. |
MotionDetect | „1 lipca 2020 r. o 12:00 wykryto ruch”. |
Te cechy obsługują dalsze odpowiedzi:
Kasa | Zdarzenia |
---|---|
AlarDisarm | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.ArmDisarm . Na przykład: „System alarmowy został włączony”.
|
blokada | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock . Na przykład: „drzwi frontowe zostały zablokowane” lub „drzwi frontowe zostały zablokowane”.
|
Sterowaniesiecią | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.TestNetworkSpeed . Na przykład: „Twój test szybkości sieci zakończył się. Szybkość pobierania na routerze w biurze to obecnie 80,2 kb/s, a szybkość wysyłania wynosi 9,3 kb/s”.
|
OpenClose | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.OpenClose . Na przykład: „Nie udało się otworzyć drzwi wejściowych” lub „Nie udało się otworzyć drzwi wejściowych”.
|
StartStop | Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.StartStop . Na przykład: „Odkurzacz został uruchomiony”.
|
Wszystkie typy urządzeń obsługują powiadomienia dotyczące określonych cech.
Tworzenie powiadomień dotyczących inteligentnego działania domu
Dodaj powiadomienia do działania smart home w tych etapach:
- Poinformuj Google, czy powiadomienia z aplikacji smart home są włączone. Jeśli użytkownicy włączyli lub wyłączyli powiadomienia w Twojej aplikacji, wyślij do
SYNC
prośbę o zmianę urządzenia. - Gdy nastąpi odpowiednie zdarzenie na urządzeniu lub zmiana stanu, które powoduje wysłanie powiadomienia, wyślij żądanie powiadomienia, wywołując interfejs Report State
reportStateAndNotification
API. W przypadku zmiany stanu urządzenia w wywołaniu Report State i powiadomienia możesz wysyłać informacje o stanie i ładunku powiadomień.
Poniżej znajdziesz szczegółowe omówienie tych czynności.
Określ, czy w aplikacji są włączone powiadomienia
Użytkownicy mogą określić, czy chcą otrzymywać aktywne powiadomienia, włączając tę funkcję w GHA. W aplikacji przeznaczonej dla urządzenia z smart home możesz też opcjonalnie włączyć opcję jawnego przełączania powiadomień z urządzenia przez użytkownika, na przykład w ustawieniach aplikacji.
Poinformuj Google, że na Twoim urządzeniu są włączone powiadomienia, wywołując opcję Poproś o synchronizację, aby zaktualizować dane urządzenia. Wyślij takie żądanie SYNC
za każdym razem, gdy użytkownik zmieni to ustawienie w Twojej aplikacji.
W odpowiedzi SYNC
wyślij jedną z tych zmian:
- Jeśli użytkownik wyraźnie przełączył powiadomienia w aplikacji na urządzeniu lub jeśli nie widzisz 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
.
Fragment kodu poniżej pokazuje, jak ustawić odpowiedź SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Wysyłaj żądania powiadomień do Google
Aby aktywować powiadomienia w Assistant, Twoja realizacja wysyła ładunek powiadomień do Google Home Graph za pomocą wywołania interfejsu Report State i Notification API.
Włącz Google HomeGraph API
-
W Google Cloud Platform Console przejdź na stronę HomeGraph API.
Otwórz stronę HomeGraph API - Wybierz projekt zgodny z identyfikatorem projektu smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z GCP Console:
-
W aplikacji GCP Console otwórz stronę Utwórz klucz konta usługi.
Otwórz stronę tworzenia 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 kont usługi.
W polu Typ klucza wybierz opcję JSON.
- Kliknij Utwórz. Plik JSON zawierający klucz 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 platformę dla zdarzenia wywołującego powiadomienie. eventId
powinien być losowym identyfikatorem, który różni się za każdym razem, gdy wysyłasz żądanie powiadomienia.
W obiekcie notifications
przekazywanym w wywołaniu interfejsu API podaj wartość priority
, która określa, jak powinno wyglądać powiadomienie. Obiekt notifications
może zawierać różne pola w zależności od cech urządzenia.
Aby ustawić ładunek i wywołać interfejs API, wykonaj jedną z tych czynności:
Wyślij aktywny ładunek powiadomień
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API udostępnia punkt końcowy HTTP.
- Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu 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
agentUserId
. Oto przykładowe żądanie JSON dla Report State i Powiadomienie: - Połącz Report State oraz JSON powiadomienia i token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń
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 Home Graph API udostępnia punkt końcowy gRPC.
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metody ReportStateAndNotificationRequest. Zwraca wartośćPromise
z atrybutem 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 Home Graph interfejsu API.
- Zainicjuj aplikację
HomeGraphApiService
przy użyciu 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 uzupełniającej
Ładunek dla odpowiedzi uzupełniającej zawiera stan żądania, kody błędów awarii (w stosownych przypadkach) i prawidłowy nagłówek followUpToken
podany w żądaniu intencji EXECUTE
. followUpToken
musi zostać użyty w ciągu 5 minut, aby zachować ważność i prawidłowo powiązać odpowiedź z pierwotnym żądaniem.
Fragment kodu poniżej pokazuje 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
do wyświetlania powiadomień tylko na urządzeniu, z którym użytkownik pierwotnie skontaktował się, a nie na inne urządzenia.
Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:
HTTP
Interfejs Home Graph API udostępnia punkt końcowy HTTP.
- Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu 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
agentUserId
. Oto przykładowe żądanie JSON dla Report State i Powiadomienie: - Połącz Report State oraz JSON powiadomienia i token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń
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 Home Graph API udostępnia punkt końcowy gRPC.
- Pobierz definicję usługi buforów protokołów dla interfejsu API Home Graph.
- Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
- Wywołaj metodę ReportStateAndNotification.
Node.js
Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metody ReportStateAndNotificationRequest. Zwraca wartośćPromise
z atrybutem 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 Home Graph interfejsu API.
- Inicjowanie
HomeGraphApiService
przy użyciu 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);
Logowanie
Powiadomienia obsługują logowanie zdarzeń zgodnie z opisem w artykule Dostęp do dzienników zdarzeń za pomocą Cloud Logging. Logi te są przydatne podczas testowania i utrzymywania wysokiej jakości powiadomień w działaniu.
Oto schemat wpisu notificationLog
:
Właściwość | Opis |
---|---|
requestId |
Identyfikator żądania powiadomienia. |
structName |
Nazwa struktury powiadomień, na przykład „ObjectDetection”. |
status |
Określa 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 akcjach, które nie zostały jeszcze uruchomione w środowisku produkcyjnym.
Przykładowe stany:
Stan | Opis |
---|---|
EVENT_ID_MISSING |
Brakuje wymaganego pola eventId .
|
PRIORITY_MISSING |
Oznacza, że brakuje pola priority .
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Wskazuje, że właściwość notificationSupportedByAgent urządzenia zgłaszającego podana w polu SYNC jest nieprawidłowa.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu, które wysyła powiadomienia: GHA. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Wskazuje, że użytkownik nie przypisał urządzenia do powiadomień do domu/struktury. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej. |
Oprócz stanów ogólnych, które mogą być stosowane do wszystkich powiadomień, pole status
może też uwzględniać informacje o określonych cechach (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).