Powiadomienia o działaniach w inteligentnym domu

Powiadomienia umożliwiają integracji Cloud-to-cloud korzystanie z funkcji Google Assistant w celu informowania 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ę.

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 bez wcześniejszych próśb użytkownika, takich jak dzwonek 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ą 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 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 wywołujące powiadomienia

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

Dodaj 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ć zarówno stan, jak i dane ładunku powiadomienia 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 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.

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

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ć 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 zamiarach 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 między usługami w chmurze. 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).