Witamy w Google Home Developer Center – nowym miejscu, z którego dowiesz się, jak tworzyć inteligentne działania domowe. Uwaga: nadal będziesz tworzyć działania w konsoli Actions.

Powiadomienia o inteligentnych domach

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Dzięki powiadomieniom działanie smart home może korzystać z Google Assistant, aby informować użytkowników o ważnych zdarzeniach lub zmianach dotyczących urządzenia. Możesz skonfigurować powiadomienia, aby na bieżąco informować użytkowników o zdarzeniach związanych z urządzeniem, na przykład o tym, że ktoś jest przy drzwiach, lub o żądaniu zmiany stanu urządzenia, na przykład informacji o tym, że zamek w samochodzie został zablokowany lub się zaciął.

Akcja smart home może wysyłać do użytkowników te rodzaje powiadomień:

  • Aktywne powiadomienia: powiadamia użytkownika o zdarzeniu związanym z urządzeniem smart home bez wcześniejszego wysyłania do niego żądań, takich jak dzwonek.

  • Dalsze odpowiedzi: potwierdzenie, że polecenie urządzenia zakończyło się powodzeniem lub niepowodzeniem, na przykład zamknięcie drzwi. Używaj tych alertów do wykonywania poleceń na urządzeniu, którego wykonanie zajmuje dużo czasu.

Assistant wysyła do użytkowników te powiadomienia 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 z Google Home app (GHA).

Zdarzenia, które powodują wyświetlanie powiadomień

W chwili wystąpienia zdarzeń na urządzeniu Realizacja działania wysyła powiadomienie do Google. Cechy urządzenia obsługiwane przez działanie smart home określają, jakie typy zdarzeń powiadomień są dostępne i jakie dane mogą być zawarte w tych powiadomieniach.

Usługi te mają proaktywne powiadomienia:

Kasa Zdarzenia
Wykrywanie obiektów Obiekty wykryte przez urządzenie, na przykład wykryte przez drzwi. Na przykład: „Alicja i Robert są przed drzwiami”.
RunCycle Urządzenie kończy cykl. Na przykład: „Cykl pralki zakończył się”.
Stan czujnika Urządzenie wykrywa obsługiwany stan czujnika. Na przykład: „Czujnik dymu wykrył dym”.
Sterowanie temperaturą Urządzenie osiągnie nastawę temperatury. Na przykład: „piekarnik został podgrzany do 350 stopni”.
AlarDisarm System przechodzi w stan wstępnego alarmu z odliczaniem wejściowym, które jest aktywowane przez otwarte drzwi.
Transmisja z kamery Link do transmisji na żywo z kamery po wykryciu przez urządzenie obiektu lub ruchu.
MotionDetect „1 lipca 2020 r. o 12:00 wykryto ruch”.

Te cechy obsługują dalsze odpowiedzi:

Kasa Zdarzenia
AlarDisarm Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.ArmDisarm. Na przykład: „System alarmowy został włączony”.
blokada Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.LockUnlock. Na przykład: „drzwi frontowe zostały zablokowane” lub „drzwi frontowe zostały zablokowane”.
Sterowaniesiecią Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.TestNetworkSpeed. Na przykład: „Twój test szybkości sieci zakończył się. Szybkość pobierania na routerze w biurze to obecnie 80,2 kb/s, a szybkość wysyłania wynosi 9,3 kb/s”.
OpenClose Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.OpenClose. Na przykład: „Nie udało się otworzyć drzwi wejściowych” lub „Nie udało się otworzyć drzwi wejściowych”.
StartStop Stan wykonania i zmiana stanu po wykonaniu polecenia urządzenia action.devices.commands.StartStop. Na przykład: „Odkurzacz został uruchomiony”.

Wszystkie typy urządzeń obsługują powiadomienia dotyczące określonych cech.

Tworzenie powiadomień dotyczących inteligentnego działania domu

Dodaj powiadomienia do działania smart home w tych etapach:

  1. Poinformuj Google, czy powiadomienia z aplikacji smart home są włączone. Jeśli użytkownicy włączyli lub wyłączyli powiadomienia w Twojej aplikacji, wyślij do SYNC prośbę o zmianę urządzenia.
  2. Gdy nastąpi odpowiednie zdarzenie na urządzeniu lub zmiana stanu, które powoduje wysłanie powiadomienia, wyślij żądanie powiadomienia, wywołując interfejs Report State reportStateAndNotification API. W przypadku zmiany stanu urządzenia w wywołaniu Report State i powiadomienia możesz wysyłać informacje o stanie i ładunku powiadomień.

Poniżej znajdziesz szczegółowe omówienie tych czynności.

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

Użytkownicy mogą określić, czy chcą otrzymywać aktywne powiadomienia, włączając tę funkcję w GHA. W aplikacji przeznaczonej dla urządzenia z smart home możesz też opcjonalnie włączyć opcję jawnego przełączania powiadomień z urządzenia przez użytkownika, na przykład w ustawieniach aplikacji.

Poinformuj Google, że na Twoim urządzeniu są włączone powiadomienia, wywołując opcję Poproś o synchronizację, aby zaktualizować dane urządzenia. Wyślij takie żądanie SYNC za każdym razem, gdy użytkownik zmieni to ustawienie w Twojej aplikacji.

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

  • Jeśli użytkownik wyraźnie przełączył powiadomienia w aplikacji na urządzeniu lub jeśli nie widzisz 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.

Fragment kodu poniżej pokazuje, jak ustawić odpowiedź SYNC:

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

Wysyłaj żądania powiadomień do Google

Aby aktywować powiadomienia w Assistant, Twoja realizacja wysyła ładunek powiadomień do Google Home Graph za pomocą wywołania interfejsu Report State i Notification API.

Włącz Google HomeGraph API

  1. W Google Cloud Platform Console przejdź na stronę HomeGraph API.

    Otwórz stronę HomeGraph API
  2. Wybierz projekt zgodny z identyfikatorem projektu smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z GCP Console:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz właściwego projektu GCP. To jest projekt zgodny z Twoim identyfikatorem projektu smart home.
  1. W aplikacji GCP Console otwórz stronę Utwórz klucz konta usługi.

    Otwórz stronę tworzenia 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 kont usługi.

  6. W polu Typ klucza wybierz opcję JSON.

  7. Kliknij Utwórz. Plik JSON zawierający klucz 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 platformę dla zdarzenia wywołującego powiadomienie. eventId powinien być losowym identyfikatorem, który różni się za każdym razem, gdy wysyłasz żądanie powiadomienia.

W obiekcie notifications przekazywanym w wywołaniu interfejsu API podaj wartość priority, która określa, jak powinno wyglądać powiadomienie. Obiekt notifications może zawierać różne pola w zależności od cech urządzenia.

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

Wyślij aktywny ładunek powiadomień

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

HTTP

Interfejs Home Graph API udostępnia punkt końcowy HTTP.

  1. Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu 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 agentUserId. Oto przykładowe żądanie JSON dla Report State i Powiadomienie:
  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 oraz JSON powiadomienia i token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń 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 Home Graph API udostępnia 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 deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.

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

  1. Zainicjuj aplikację HomeGraphApiService przy użyciu 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 uzupełniającej

Ładunek dla odpowiedzi uzupełniającej zawiera stan żądania, kody błędów awarii (w stosownych przypadkach) i prawidłowy nagłówek followUpToken podany w żądaniu 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.

Fragment kodu poniżej 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 do wyświetlania powiadomień tylko na urządzeniu, z którym użytkownik pierwotnie skontaktował się, a nie na inne urządzenia.

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

HTTP

Interfejs Home Graph API udostępnia punkt końcowy HTTP.

  1. Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu 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 agentUserId. Oto przykładowe żądanie JSON dla Report State i Powiadomienie:
  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 oraz JSON powiadomienia i token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń 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 Home Graph API udostępnia 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 deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.

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

  1. Inicjowanie HomeGraphApiService przy użyciu 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ą logowanie zdarzeń zgodnie z opisem w artykule Dostęp do dzienników zdarzeń za pomocą Cloud Logging. Logi te są przydatne podczas testowania i utrzymywania wysokiej jakości powiadomień w działaniu.

Oto schemat wpisu notificationLog:

Właściwość Opis
requestId Identyfikator żądania powiadomienia.
structName Nazwa struktury powiadomień, na przykład „ObjectDetection”.
status Określa 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 akcjach, które nie zostały jeszcze uruchomione w środowisku produkcyjnym.

Przykładowe stany:

Stan Opis
EVENT_ID_MISSING Brakuje wymaganego pola eventId.
PRIORITY_MISSING Oznacza, że brakuje pola priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Wskazuje, że właściwość notificationSupportedByAgent urządzenia zgłaszającego podana w polu SYNC jest nieprawidłowa.
NOTIFICATION_ENABLED_BY_USER_FALSE Wskazuje, że użytkownik nie włączył powiadomień na urządzeniu, które wysyła powiadomienia: GHA. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Wskazuje, że użytkownik nie przypisał urządzenia do powiadomień do domu/struktury. Ten stan jest dostępny tylko w działaniach, które nie zostały jeszcze uruchomione w wersji produkcyjnej.

Oprócz stanów ogólnych, które mogą być stosowane do wszystkich powiadomień, pole status może też uwzględniać informacje o określonych cechach (np. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).