Powiadomienia o działaniach w inteligentnym domu

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:

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

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

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt pasujący do identyfikatora projektu w smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

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

Uwaga: podczas wykonywania tych czynności sprawdź, czy używasz właściwego projektu GCP. Ten projekt pasuje do identyfikatora projektu w smart home.
  1. W sekcji Google Cloud Console otwórz stronę Tworzenie klucza konta usługi.

    Otwórz stronę Tworzenie klucza konta usługi
  2. Z listy 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. Z listy Rola wybierz Konta usługi > Twórca tokenów konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

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

  1. 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.
  2. Uzyskaj token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph za pomocą oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON z atrybutem agentUserId. Oto przykładowe żądanie JSON dla 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 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:
  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 zapewnia punkt końcowy gRPC

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

Node.js

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

  1. Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z metodą ReportStateAndNotificationRequest. Zwraca wartość Promise z parametrem 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 API HomeGraph dla języka Java zawiera powiązania dla interfejsu API Home Graph.

  1. Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą metody 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();

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

  1. 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.
  2. Uzyskaj token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph za pomocą oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON z atrybutem agentUserId. Oto przykładowe żądanie JSON dla 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 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:
  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 zapewnia punkt końcowy gRPC

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

Node.js

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

  1. Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification z metodą ReportStateAndNotificationRequest. Zwraca wartość Promise z parametrem 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 API HomeGraph dla języka Java zawiera powiązania dla interfejsu API Home Graph.

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