Powiadomienia o działaniach w inteligentnym domu

Powiadomienia umożliwiają Cloud-to-cloudintegracjiGoogle Assistant komunikowanie się z użytkownikami w sprawie ważnych zdarzeń lub zmian związanych z urządzeniem. Możesz wdrożyć powiadomienia, aby informować użytkowników o zdarzeniach na urządzeniu, np. gdy ktoś jest przy drzwiach, lub zgłaszać zmiany stanu urządzenia, np. gdy zamek drzwi został prawidłowo zablokowany lub zaciął się.

Integracja Cloud-to-cloud może wysyłać do użytkowników te typy powiadomień:

• Proaktywne powiadomienia: alerty o smart homezdarzeniu na urządzeniu, które są wysyłane do użytkownika bez wcześniejszych próśb do urządzenia, np. dzwonek do drzwi.

• Odpowiedzi uzupełniające: potwierdzenie, że żądanie polecenia urządzenia zakończyło się powodzeniem lub niepowodzeniem, np. podczas zamykania drzwi. Używaj tych alertów w przypadku poleceń dotyczących urządzeń, których wykonanie zajmuje trochę czasu. Odpowiedzi uzupełniające są obsługiwane tylko wtedy, gdy żądania poleceń urządzenia są wysyłane z głośników i wyświetlaczy inteligentnych.

Assistant udostępnia te powiadomienia użytkownikom w formie komunikatów na głośnikach i wyświetlaczach inteligentnych. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia z poziomu Google Home app (GHA).

Zdarzenia, które wywołują powiadomienia

Gdy wystąpią zdarzenia na urządzeniu, usługa realizacji wysyła do Google żądanie powiadomienia. Cechy urządzenia obsługiwane przez Cloud-to-cloudintegrację określają, jakie typy zdarzeń powiadomień są dostępne i jakie dane możesz uwzględnić w tych powiadomieniach.

Powiadomienia proaktywne są obsługiwane w przypadku tych cech:

Te cechy obsługują odpowiedzi uzupełniające:

Powiadomienia dotyczące odpowiednich cech są obsługiwane na wszystkich typach urządzeń.

Tworzenie powiadomień dla integracji z chmury do chmury

Dodaj powiadomienia do integracji Cloud-to-cloud na tych etapach:

1. Poinformuj Google, czy powiadomienia są włączone w aplikacji na urządzeniu. Jeśli użytkownicy włączą lub wyłączą powiadomienia w Twojej aplikacji, wyślij żądanie SYNC, aby poinformować Google o zmianie na urządzeniu.smart home
2. Gdy wystąpi odpowiednie zdarzenie na urządzeniu lub zmiana stanu, która wywołuje powiadomienie, wyślij żądanie powiadomienia, wywołując interfejs API Report State reportStateAndNotification. Jeśli stan urządzenia się zmienił, możesz wysłać zarówno stan, jak i ładunek powiadomienia w wywołaniu Report State i Notification.

Więcej informacji o tych krokach znajdziesz w kolejnych sekcjach.

Informowanie o tym, czy powiadomienia są włączone w aplikacji

Użytkownicy mogą wybrać, czy chcą otrzymywać proaktywne powiadomienia, włączając tę funkcję w GHA. W aplikacji na urządzenie smart homemożesz też opcjonalnie dodać możliwość włączania i wyłączania powiadomień z urządzenia przez użytkowników, np. w ustawieniach aplikacji.

Poinformuj Google, że powiadomienia są włączone na Twoim urządzeniu, wykonując wywołanie Request SYNC, aby zaktualizować dane urządzenia. Takie żądanie SYNC należy wysyłać za każdym razem, gdy użytkownicy zmienią to ustawienie w Twojej aplikacji.

W SYNC odpowiedzi wyślij jedną z tych aktualizacji:

• Jeśli użytkownik włączył powiadomienia w aplikacji na urządzeniu lub jeśli nie udostępniasz opcji przełączania, ustaw wartość właściwości devices.notificationSupportedByAgent na true.
• Jeśli użytkownik wyraźnie wyłączył powiadomienia w aplikacji na urządzeniu, ustaw wartość właściwości devices.notificationSupportedByAgent na false.

Poniższy fragment kodu pokazuje, jak ustawić odpowiedź SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

wysyłać do Google żądania powiadomień,

Aby wywołać powiadomienia na Assistant, usługa realizacji wysyła ładunek powiadomienia do Google Home Graph za pomocą Report State i wywołania interfejsu Notification API.

Włączanie interfejsu Google HomeGraph API

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

   Otwórz stronę HomeGraph API
2. Wybierz projekt, który pasuje do Twojego identyfikatora projektu smart home.
3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

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

1. W konsoli Google Cloud Console otwórz stronę Konta usługi.

   Otwórz stronę Konta usługi.

   Zanim przejdziesz na stronę Konta usługi, być może musisz wybrać projekt.

2. Kliknij addUtwórz konto usługi.

3. W polu Nazwa konta usługi wpisz nazwę.

4. W polu Identyfikator konta usługi wpisz identyfikator.

5. W polu Opis konta usługi wpisz opis.

6. Kliknij Utwórz i kontynuuj.

7. W menu Rola wybierz Konta usługi > Twórca tokenów tożsamości OpenID Connect konta usługi.

8. Kliknij Dalej.

9. Kliknij Gotowe.

10. Wybierz z listy kont usług utworzone przed chwilą konto usługi i w menu more_vert Działania kliknij Zarządzaj kluczami.

11. Kliknij Dodaj klucz > Utwórz nowy klucz.

12. W polu Typ klucza wybierz opcję JSON.

13. Kliknij Utwórz. Na komputer zostanie pobrany plik JSON zawierający klucz.

Wysyłanie powiadomienia

Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification. Żądanie JSON musi zawierać parametr eventId, który jest unikalnym identyfikatorem generowanym przez Twoją platformę dla zdarzenia wywołują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 API uwzględnij wartość priority, która określa sposób wyświetlania powiadomienia. Obiekt notifications może zawierać różne pola w zależności od cechy urządzenia.

Aby ustawić ładunek i wywołać interfejs API, wykonaj jedną z tych czynności:

• Wysyłanie ładunku aktywnego powiadomienia
• Wysyłanie ładunku z odpowiedzią uzupełniającą

Wysyłanie ładunku aktywnego powiadomienia

Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:

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
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 uzupełniającej

Ładunek odpowiedzi uzupełniającej zawiera stan żądania, kody błędów w przypadku nieudanych zdarzeń (jeśli dotyczy) oraz prawidłowy obiekt followUpToken podany podczas żądania 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.

Poniższy 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 wchodził w interakcję, a nie na wszystkich urządzeniach użytkownika.

Aby wywołać interfejs API, wybierz opcję na jednej z tych kart:

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,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 Rejestrowanie w Cloud Logging w przypadku integracji typu cloud-to-cloud. Dzienniki te są przydatne do testowania i utrzymywania jakości powiadomień w ramach działania.

Oto schemat wpisu notificationLog:

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:

Oprócz tych ogólnych stanów, które mogą dotyczyć wszystkich powiadomień, pole status może też zawierać stany dotyczące konkretnych cech, jeśli ma to zastosowanie (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).