Powiadomienia umożliwiają działanie smart home Google Assistant służy do przekazywania użytkownikom ważnych informacji zdarzeń i zmian związanych z urządzeniami. Możesz zaimplementować powiadomienia, aby otrzymywać alerty aby powiadamiać użytkowników o zdarzeniach związanych z urządzeniem, np. gdy ktoś jest przy drzwiach lub gdy ktoś raportują o żądanej zmianie stanu urządzenia, na przykład o tym, że zasuwka zamka do drzwi udało się jej zaangażować.
Akcja smart home może wysyłać te typy powiadomienia wysyłane do użytkowników.
Aktywne powiadomienia: powiadamia o użytkowniku smart home na urządzeniu, na którym użytkownik nie wysyłał żadnych wcześniejszych żądań, takich jak dzwonek do drzwi.
Odpowiedzi dodatkowe: potwierdzenie, że żądanie polecenia na urządzeniu zostało wysłane. uda się lub nie udało, na przykład przy zamykaniu zamka w drzwiach. Użyj tych alertów do: na urządzeniach, których wykonanie wymaga czasu. Dalsze odpowiedzi są tylko obsługiwane, gdy żądania poleceń urządzenia są wysyłane z inteligentnych głośników i inteligentnych i wyświetlacze.
Assistant udostępnia te powiadomienia użytkownikom jako 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 na Google Home app (GHA)
Zdarzenia wyzwalające powiadomienia
W przypadku wystąpienia zdarzeń na urządzeniu usługa Realizacja akcji wysyła prośbę o powiadomienie. o korzystaniu. Cechy urządzenia, których akcja smart home określa, jakie typy zdarzeń powiadomień są dostępne, które możesz uwzględnić w powiadomieniach.
Te funkcje obsługują aktywne powiadomienia:
Cecha | Wydarzenia |
---|---|
ObjectDetection | obiekty wykryte przez urządzenie, na przykład rozpoznane twarze. wykrywany przy drzwiach. Na przykład: „Alicja i Robert są przy drzwiach frontowych”. |
RunCycle | Urządzenie kończy cykl. Na przykład: „Cykl pralki zostało zakończone”. |
SensorState | Urządzenie wykrywa stan obsługiwanego czujnika. Na przykład: „Czujnik dymu wykrył dym” |
Te cechy umożliwiają dodatkowe odpowiedzi:
Cecha | Wydarzenia |
---|---|
LockUnlock | Stan zakończenia i zmiana stanu po wykonaniu polecenia
action.devices.commands.LockUnlock polecenie na urządzeniu. Dla:
na przykład: „Zamknięto drzwi frontowe” lub „Zacięto się w drzwiach wejściowych”.
|
NetworkControl | Stan zakończenia i zmiana stanu po wykonaniu polecenia
action.devices.commands.TestNetworkSpeed polecenie na urządzeniu. Dla:
przykład: „Test szybkości sieci dobiegł końca. Prędkość pobierania na
obecnie 80,2 kb/s w biurze, a szybkość wysyłania – 9,3 kb/s”.
|
OpenClose | Stan zakończenia i zmiana stanu po wykonaniu polecenia
action.devices.commands.OpenClose polecenie na urządzeniu. Dla:
na przykład: „Otwarto drzwi wejściowe” lub „Nie udało się otworzyć drzwi frontowych”.
|
Wszystkie typy urządzeń obsługują powiadomienia dotyczące odpowiednich cech.
Tworzenie powiadomień dotyczących akcji inteligentnego domu
Dodawanie powiadomień do działania smart home na tych etapach:
- Wskaż Google, czy powiadomienia są włączone na
smart home aplikacja na urządzeniu. Jeśli użytkownicy włączą lub wyłączą powiadomienia
w swojej aplikacji wyślij żądanie
SYNC
, aby poinformować Google o zmianie urządzenia. - Gdy wystąpi odpowiednie zdarzenie lub zmiana stanu urządzenia, które aktywuje
powiadomienia, wyślij prośbę o powiadomienie, wywołując
Report State
reportStateAndNotification
API. Jeśli stan urządzenia uległ zmianie, możesz wysłać zarówno stan, jak i ładunek powiadomień w Report State i w powiadomieniu.
W kolejnych sekcjach znajdziesz bardziej szczegółowe informacje o tych czynnościach.
Określ, czy w aplikacji są włączone powiadomienia
Użytkownicy mogą wybrać, czy chcą otrzymywać aktywne powiadomienia przez włączenie tej funkcji w GHA. W aplikacji dla urządzenia smart home, możesz też opcjonalnie dodać możliwość użytkowników, aby wyraźnie przełączać powiadomienia z urządzenia, na przykład z ustawieniach aplikacji.
Aby poinformować Google, że powiadomienia są włączone na Twoim urządzeniu, ustaw
a Poproś o rozmowęw zakresie SYNCHRONIZACJI
, by zaktualizować dane urządzenia. Wyślij takie żądanie SYNC
za każdym razem,
użytkownicy mogą zmienić to ustawienie w Twojej aplikacji.
W odpowiedzi z SYNC
wyślij jedną z tych informacji:
- Jeśli użytkownik samodzielnie włączył powiadomienia w aplikacji na urządzeniu lub
nie udostępni opcji przełączania, ustaw
devices.notificationSupportedByAgent
do usługitrue
. - Jeśli użytkownik wprost wyłączył powiadomienia w aplikacji na urządzeniu, ustaw
devices.notificationSupportedByAgent
do usługifalse
.
Poniższy fragment kodu pokazuje, jak skonfigurować odpowiedź SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Wysyłaj prośby o powiadomienia do Google
Aby otrzymywać powiadomienia na urządzeniu Assistant, realizacja wysyła ładunek powiadomień do Google Home Graph za pomocą Report State i wywołania interfejsu Notification API.
Włączanie interfejsu Google HomeGraph API
-
W Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API - Wybierz projekt, który pasuje do identyfikatora projektu smart home.
- Kliknij WŁĄCZ.
Tworzenie klucza konta usługi
Aby wygenerować klucz konta usługi z Google Cloud Console, wykonaj te instrukcje:
-
W 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.
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 pobrane na komputer.
Wyślij powiadomienie
Wywołaj prośbę o powiadomienie za pomocą
devices.reportStateAndNotification
API.
Żądanie JSON musi zawierać eventId
, który jest unikalnym identyfikatorem generowanym przez
platformę zdarzenia, które ma wywoływać powiadomienie. Element eventId
powinien
to losowy identyfikator, który jest inny za każdym razem, gdy wysyłasz prośbę o powiadomienie.
W obiekcie notifications
przekazywanym w wywołaniu interfejsu API wstaw
Wartość priority
, która określa sposób przedstawiania powiadomienia. Twoje
Obiekt notifications
może zawierać różne pola w zależności od urządzenia
cechę.
Wykonaj jedną z tych ścieżek, aby ustawić ładunek i wywołać interfejs API:
Wysyłanie proaktywnego ładunku powiadomień
Aby wywołać interfejs API, wybierz opcję z 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ć plik JSON Web Token (JWT). Więcej informacji: Uwierzytelnianie przy użyciu konta usługi.
- Uzyskaj token dostępu OAuth 2.0 za pomocą
https://www.googleapis.com/auth/homegraph
zakres używa oauth2l: - Utwórz żądanie JSON za pomocą
agentUserId
. Oto przykładowe żądanie JSON dla Report State i powiadomienia: - Połącz pliki JSON Report State i Notification JSON z tokenem w żądaniu HTTP POST
do punktu końcowego Google Home Graph. Oto przykład,
żądania w wierszu poleceń za pomocą polecenia
curl
jako test:
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 buforów protokołów dla 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.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metody ReportStateAndNotificationRequest. ZwracaPromise
z funkcją 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 zawiera powiązania dla interfejsu Home Graph API.
- Zainicjuj
HomeGraphApiService
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą funkcjiReportStateAndNotificationRequest
. 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 ładunku odpowiedzi
Ładunek kolejnej odpowiedzi zawiera stan żądania, błąd,
kody błędów zdarzeń (jeśli mają zastosowanie) i prawidłowy kod followUpToken
,
podane podczas żądania intencji EXECUTE
. Należy użyć pola followUpToken
w ciągu 5 minut, aby odpowiedź była ważna i prawidłowo kojarzona.
z pierwotną prośbą.
Ten fragment kodu zawiera przykładowy ładunek żądania EXECUTE
z
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
użytkownik wszedł w interakcję z reklamą, ale nie przesyłał jej
urządzeniach użytkowników.
Aby wywołać interfejs API, wybierz opcję z 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ć plik JSON Web Token (JWT). Więcej informacji: Uwierzytelnianie przy użyciu konta usługi.
- Uzyskaj token dostępu OAuth 2.0 za pomocą
https://www.googleapis.com/auth/homegraph
zakres używa oauth2l: - Utwórz żądanie JSON za pomocą
agentUserId
. Oto przykładowe żądanie JSON dla Report State i powiadomienia: - Połącz pliki JSON Report State i Notification JSON z tokenem w żądaniu HTTP POST
do punktu końcowego Google Home Graph. Oto przykład,
żądania w wierszu poleceń za pomocą polecenia
curl
jako test:
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 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.
- Zainicjuj usługę
google.homegraph
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą metody ReportStateAndNotificationRequest. ZwracaPromise
z funkcją 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 zawiera powiązania dla interfejsu Home Graph API.
- Zainicjuj
HomeGraphApiService
przy użyciu domyślnych danych logowania aplikacji. - Wywołaj metodę
reportStateAndNotification
za pomocą funkcjiReportStateAndNotificationRequest
. 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(); // 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 logów zdarzeń za pomocą Cloud Logging. Te logi są przydatne do testowania i utrzymywania jakości powiadomień w akcję.
Oto schemat wpisu notificationLog
:
Właściwość | Opis |
---|---|
requestId |
Identyfikator prośby o powiadomienie. |
structName |
Nazwa struktury powiadomień, na przykład „ObjectDetection”. |
status |
Wskazuje stan powiadomienia. |
Pole status
zawiera różne stany, które mogą wskazywać na błędy w parametrze
ładunek powiadomień. Niektóre z nich mogą być dostępne tylko w przypadku akcji,
nie została jeszcze opublikowana 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ść false (fałsz).
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu, które wysyła powiadomienie w GHA. Ten stan jest dostępny tylko w przypadku działań, które nie są jeszcze dostępne w wersji produkcyjnej. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Wskazuje, że użytkownik nie przypisał urządzenia wysyłającego powiadomienia do domu/domu. Ten stan jest dostępny tylko w przypadku działań, które nie są jeszcze dostępne w wersji produkcyjnej. |
Oprócz tych ogólnych stanów, które mogą mieć zastosowanie do wszystkich powiadomień, pole status
może też zawierać stany związane z określonymi cechami (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).