Powiadomienia o działaniach w inteligentnym domu

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:

  1. 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.
  2. 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 na true.
  • Jeśli użytkownik wyraźnie wyłączył powiadomienia w aplikacji na urządzeniu, ustaw właściwość devices.notificationSupportedByAgent na false.

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

  1. W sekcji Google Cloud Console otwórz stronę HomeGraph API.

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt, który odpowiada Twojemu identyfikatorowi projektu smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z poziomu Google Cloud Console, wykonaj te czynności:

Uwaga: upewnij się, że podczas wykonywania tych czynności używasz właściwego projektu GCP. Jest to projekt, który pasuje do identyfikatora projektu smart home.
  1. W panelu Google Cloud Console otwórz stronę Utwórz klucz konta usługi.

    Otwórz stronę tworzenia klucza konta usługi
  2. Na liście Konto usługi wybierz Nowe konto usługi.
  3. W polu Nazwa konta usługi wpisz nazwę.
  4. W polu Identyfikator konta usługi wpisz identyfikator.
  5. Na liście Rola wybierz Konta usługi > Twórca tokena konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

  7. 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.

  1. 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.
  2. Aby uzyskać token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph, użyj polecenia oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON za pomocą agentUserId. Oto przykładowa prośba JSON dotycząca Report State i powiadomienia:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. 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:
  7. 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

  1. Pobierz definicję usługi protocol buffers interfejsu API Home Graph.
  2. Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować atrapy klienta w jednym z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsów API Google zapewnia powiązania dla interfejsu Home Graph API.

  1. Inicjuje usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca PromiseReportStateAndNotificationResponse.
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.

  1. Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca 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);
    
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.

  1. 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.
  2. Aby uzyskać token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph, użyj polecenia oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON za pomocą agentUserId. Oto przykładowa prośba JSON dotycząca Report State i powiadomienia:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. 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:
  7. 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.

  1. Pobierz definicję usługi protocol buffers interfejsu API Home Graph.
  2. Aby wygenerować atrapy klienta w jednym z obsługiwanych języków, postępuj zgodnie z instrukcjami podanymi w dokumentacji dla deweloperów gRPC.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsów API Google zapewnia powiązania dla interfejsu Home Graph API.

  1. Zainicjuj usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca PromiseReportStateAndNotificationResponse.
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.

  1. Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. 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).