Powiadomienia o działaniach w inteligentnym domu

Powiadomienia umożliwiają integracji Cloud-to-cloud korzystanie z Google Assistant do informowania użytkowników o ważnych zdarzeniach lub zmianach 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 o żądanej zmianie stanu urządzenia, np. gdy rygiel zamka drzwi został pomyślnie zablokowany lub się zaciął.

Integracja z Cloud-to-cloud może wysyłać użytkownikom te typy powiadomień:

• Aktywne powiadomienia: powiadamiają użytkownika o zdarzeniu na urządzeniu smart home bez wcześniejszych żądań użytkownika, np. o dzwonku do drzwi.

• Odpowiedzi uzupełniające: potwierdzenie, że polecenie urządzenia zostało wykonane lub nie, np. podczas blokowania drzwi. Używaj tych alertów w przypadku poleceń dotyczących urządzeń, których wykonanie zajmuje trochę czasu. Odpowiedzi na pytania dodatkowe są obsługiwane tylko wtedy, gdy żądania poleceń urządzenia są wysyłane z inteligentnych głośników i inteligentnych ekranów.

Assistant przekazuje 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 w Google Home app (GHA).

Zdarzenia, które wywołują powiadomienia

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

Te cechy obsługują aktywne powiadomienia:

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

Wszystkie typy urządzeń obsługują powiadomienia dotyczące odpowiednich cech.

Tworzenie powiadomień dotyczących integracji z chmury do chmury

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

1. Poinformuj Google, czy powiadomienia są włączone w aplikacji urządzenia smart home. Jeśli użytkownicy włączą lub wyłączą powiadomienia w aplikacji, wyślij żądanie SYNC, aby poinformować Google o zmianie na urządzeniu.
2. Gdy wystąpi odpowiednie zdarzenie na urządzeniu lub zmiana stanu, która wyzwala powiadomienie, 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 ładunek powiadomienia w wywołaniu Report State i wywołaniu powiadomienia.

W kolejnych sekcjach znajdziesz bardziej szczegółowe informacje o tych krokach.

Wskazywanie, czy powiadomienia są włączone w aplikacji

Użytkownicy mogą wybrać, czy chcą otrzymywać aktywne powiadomienia, włączając tę funkcję w GHA. W aplikacji na urządzenie smart home możesz też opcjonalnie dodać możliwość wyraźnego przełączania powiadomień z urządzenia przez użytkowników, na przykład w ustawieniach aplikacji.

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

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

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

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

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

Wysyłanie próśb o powiadomienia do Google

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

Włączanie interfejsu Google HomeGraph API

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

   Otwórz stronę HomeGraph API
2. Wybierz projekt, który odpowiada identyfikatorowi 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 Google Cloud Console otwórz stronę Konta usługi.

   Otwórz stronę Konta usługi

   Zanim przejdziesz na stronę Konta usługi, może być konieczne wybranie projektu.

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 utworzone konto usługi z listy kont usługi i wybierz Zarządzaj kluczami z menu more_vert Działania.

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

12. W polu Typ klucza wybierz opcję JSON.

13. Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na komputer.

Wyślij powiadomienie

Wywołaj żądanie powiadomienia za pomocą interfejsu API devices.reportStateAndNotification. Żądanie JSON musi zawierać parametr eventId, który jest unikalnym identyfikatorem wygenerowanym 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 prośbę o powiadomienie.

W obiekcie notifications, który przekazujesz w wywołaniu interfejsu API, uwzględnij wartość priority, która określa, jak powinno być prezentowane powiadomienie. 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 odpowiedzi dodatkowej

Wysyłanie danych 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 na dodatkowe pytanie

Ładunek odpowiedzi uzupełniającej zawiera stan żądania, kody błędów w przypadku niepowodzenia zdarzenia (jeśli dotyczy) oraz prawidłowy parametr followUpToken podany podczas żądania intencji EXECUTE. Aby zachować ważność i prawidłowo powiązać odpowiedź z pierwotnym żądaniem, należy użyć followUpToken w ciągu 5 minut.

Poniższy fragment kodu 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, aby wyświetlać powiadomienie tylko na urządzeniu, z którego użytkownik korzystał, a nie na wszystkich jego urządzeniach.

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 artykule Cloud Logging w przypadku integracji między chmurami. Te logi są przydatne do testowania i utrzymywania jakości powiadomień w akcji.

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 akcji, które nie zostały jeszcze uruchomione w środowisku produkcyjnym.

Przykładowe stany:

Oprócz tych ogólnych stanów, które mogą dotyczyć wszystkich powiadomień, pole status może też zawierać stany związane z cechami (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).