Powiadomienia o działaniach w inteligentnym domu

Powiadomienia umożliwiają integracji Cloud-to-cloud korzystanie z funkcji Google Assistant do komunikowania się z użytkownikami na temat ważnych zdarzeń lub zmian 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ę.

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

• Powiadomienia proaktywne: informują użytkownika o zdarzeniach na urządzeniu smart home, które nie zostały wywołane przez użytkownika, np. o dzwonku do drzwi.

• 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ą więcej czasu na wykonanie. Odpowiedzi uzupełniające są obsługiwane tylko wtedy, gdy żądania poleceń na urządzeniu są wysyłane z inteligentnych głośników i inteligentnych ekranów.

Assistant wysyła te powiadomienia do użytkowników w postaci komunikatów na głośnikach i ekranach inteligentnych. Aktywne powiadomienia są domyślnie wyłączone. Użytkownicy mogą włączać i wyłączać wszystkie aktywne powiadomienia z Google Home app (GHA).

Zdarzenia, które powodują wysyłanie powiadomień

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

Te cechy obsługują powiadomienia proaktywne:

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

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

Tworzenie powiadomień dla integracji z chmury do chmury

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

1. Powiadom 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 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ć stan i dane powiadomienia razem w wywołaniu Report State i powiadomieniu.

W następnych sekcjach omawiamy te czynności bardziej szczegółowo.

Określ, czy powiadomienia są włączone w Twojej aplikacji

Użytkownicy mogą wybrać, 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ń z urządzenia, na przykład w ustawieniach aplikacji.

Wskaż Google, że powiadomienia są włączone na Twoim urządzeniu, wysyłając wywołanie Request SYNC, aby zaktualizować dane urządzenia. Gdy użytkownicy zmieniają to ustawienie w aplikacji, powinieneś wysłać prośbę SYNC.

W odpowiedzi na SYNC prześlij jedną z tych informacji:

• Jeśli użytkownik wyraźnie włączył powiadomienia w aplikacji na urządzeniu lub jeśli nie udostępniasz opcji przełącznika, 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łanie żądań powiadomień 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 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:

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

   Otwórz stronę Konta usługi.

   Zanim przejdziesz na stronę Konta usługi, musisz może 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. Na liście kont usług wybierz właśnie utworzone 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. Plik JSON zawierający klucz zostanie pobrany na komputer.

Wysyłanie powiadomienia

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, które wywołało 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 zasobów aktywnych powiadomień
• Wysyłanie danych odpowiedzi

Wysyłanie 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 danych odpowiedzi na prośbę o dodatkowe informacje

Dane dotyczące odpowiedzi na żądanie zawierają stan żądania, kody błędów zdarzeń (jeśli występują) oraz prawidłowy obiekt followUpToken podany podczas żądania o zamierzeniu 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:

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 Rejestrowanie zdarzeń w chmurze w przypadku przesyłania danych z chmury do chmury. Te dzienniki są przydatne do testowania i utrzymywania jakości powiadomień w Twoim widżecie.

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ń, w polu status mogą też występować stany związane z cechami (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).