Уведомления для умного дома Действия

Уведомления позволяют вашему smart home Action использовать Google Assistant , чтобы сообщать пользователям о важных событиях или изменениях, связанных с устройством. Вы можете реализовать уведомления, чтобы предупреждать пользователей о своевременных событиях устройства, например, когда кто-то находится у двери, или сообщать о запрошенном изменении состояния устройства, например, когда засов дверного замка был успешно задействован или заклинил.

Ваш smart home Action может отправлять пользователям следующие типы уведомлений:

  • Проактивные уведомления : предупреждает пользователя о событии устройства smart home без каких-либо предшествующих запросов пользователя к его устройствам, таких как звонок в дверь.

  • Последующие ответы : подтверждение того, что запрос команды устройства был успешным или неудачным, например, при запирании двери. Используйте эти оповещения для команд устройства, выполнение которых требует времени. Последующие ответы поддерживаются только в том случае, если запросы команд устройства отправляются с интеллектуальных динамиков и интеллектуальных дисплеев.

Assistant предоставляет эти уведомления пользователям в виде объявлений на интеллектуальных колонках и интеллектуальных дисплеях. По умолчанию активные уведомления отключены. Пользователи имеют возможность включать или отключать все проактивные уведомления из Google Home app (GHA) .

События, которые вызывают уведомления

Когда происходят события на устройстве, при выполнении вашего действия отправляется запрос на уведомление в Google. Характеристики устройства, которые поддерживает действие вашего smart home определяют, какие типы событий уведомлений доступны, а также данные, которые вы можете включить в эти уведомления.

Следующие особенности поддерживают упреждающие уведомления:

Черта События
ObjectDetection Объекты, обнаруженные устройством, например, когда распознанное лицо обнаружено у двери. Например: «Алиса и Боб у входной двери».
RunCycle Устройство завершает цикл. Например: «Цикл стиральной машины завершен».
SensorState Устройство обнаруживает поддерживаемое состояние датчика. Например: «Датчик дыма обнаружил дым».

Следующие черты поддерживают последующие реакции:

Черта События
LockUnlock Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.LockUnlock . Например: «Входная дверь заперта» или «Входная дверь заклинила».
NetworkControl Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.TestNetworkSpeed . Например: «Проверка скорости вашей сети завершена. Скорость загрузки на офисном маршрутизаторе в настоящее время составляет 80,2 Кбит/с, а скорость отдачи — 9,3 Кбит/с».
OpenClose Статус завершения и изменение состояния после выполнения команды устройства action.devices.commands.OpenClose . Например: «Открылась входная дверь» или «Не удалось открыть входную дверь».

Все типы устройств поддерживают уведомления о соответствующих характеристиках.

Создайте уведомления для вашего умного дома. Действие

Добавьте уведомления в свой smart home Действия на этих этапах:

  1. Сообщите Google, включены ли уведомления в приложении вашего устройства smart home . Если пользователи включают или отключают уведомления в вашем приложении, отправьте запрос SYNC , чтобы сообщить Google об изменении устройства.
  2. Когда происходит соответствующее событие устройства или изменение состояния, вызывающее уведомление, отправьте запрос на уведомление, вызвав API Report State reportStateAndNotification . Если состояние устройства изменилось, вы можете отправить как состояние, так и полезную нагрузку уведомления вместе в вызове Report State и «Уведомление».

В следующих разделах эти шаги описаны более подробно.

Укажите, включены ли уведомления в вашем приложении.

Пользователи могут выбирать, хотят ли они получать проактивные уведомления, включив эту функцию в GHA . В приложении для вашего устройства smart home вы также можете дополнительно добавить пользователям возможность явного переключения уведомлений с устройства, например, из настроек вашего приложения.

Сообщите Google, что на вашем устройстве включены уведомления, выполнив вызов Request SYNC для обновления данных устройства. Вы должны отправлять такой запрос SYNC каждый раз, когда пользователи меняют этот параметр в вашем приложении.

В ответе SYNC отправьте одно из следующих обновлений:

  • Если пользователь явно включил уведомления в приложении вашего устройства или вы не предоставили параметр переключения, установите для свойства devices.notificationSupportedByAgent значение true .
  • Если пользователь явно отключил уведомления в приложении вашего устройства, задайте для свойства devices.notificationSupportedByAgent значение false .

В следующем фрагменте показан пример настройки ответа SYNC:

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

Отправлять запросы на уведомления в Google

Чтобы активировать уведомления в Assistant , ваше выполнение отправляет полезную нагрузку уведомления в Google Home Graph через Report State и вызов API уведомлений .

Включите API Google HomeGraph

  1. В Google Cloud Console перейдите на страницу HomeGraph API .

    Перейдите на страницу API HomeGraph.
  2. Выберите проект, который соответствует идентификатору вашего проекта smart home .
  3. Нажмите ВКЛЮЧИТЬ .

Создайте ключ сервисной учетной записи

Следуйте этим инструкциям, чтобы сгенерировать ключ сервисного аккаунта из Google Cloud Console :

Примечание . При выполнении этих шагов убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует идентификатору вашего проекта smart home .
  1. В Google Cloud Console перейдите на ключевую страницу создания сервисного аккаунта .

    Перейдите на страницу создания ключа учетной записи службы.
  2. В списке Учетная запись службы выберите Новая учетная запись службы .
  3. В поле Имя учетной записи службы введите имя.
  4. В поле «Идентификатор учетной записи службы» введите идентификатор.
  5. В списке Роль выберите Учетные записи служб > Создатель токенов учетной записи службы .

  6. В качестве типа ключа выберите параметр JSON .

  7. Нажмите Создать . Файл JSON, содержащий ваш ключ, загружается на ваш компьютер.

Отправить уведомление

Выполните вызов запроса на уведомление с помощью API devices.reportStateAndNotification . Ваш запрос JSON должен включать eventId — уникальный идентификатор, сгенерированный вашей платформой для события, вызывающего уведомление. eventId должен быть случайным идентификатором, который меняется каждый раз, когда вы отправляете запрос на уведомление.

В объект notifications , который вы передаете в вызове API, включите значение priority , которое определяет, как должно быть представлено уведомление. Ваш объект notifications может включать в себя разные поля в зависимости от характеристик устройства.

Следуйте одному из этих путей, чтобы установить полезную нагрузку и вызвать API:

Отправка упреждающего уведомления

Чтобы вызвать API, выберите вариант на одной из этих вкладок:

HTTP

API Home Graph предоставляет конечную точку HTTP.

  1. Используйте загруженный файл JSON учетной записи службы, чтобы создать веб-токен JSON (JWT). Дополнительные сведения см. в разделе Аутентификация с использованием учетной записи службы .
  2. Получите токен доступа OAuth 2.0 с областью действия https://www.googleapis.com/auth/homegraph , используя oauth2l :
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Создайте запрос JSON с agentUserId . Вот пример запроса JSON для Report State и уведомления:
  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. Объедините JSON Report State и уведомления и токен в вашем запросе HTTP POST к конечной точке Google Home Graph. Вот пример того, как сделать запрос в командной строке с помощью 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

API Home Graph предоставляет конечную точку gRPC.

  1. Получите определение службы буферов протокола для API Home Graph .
  2. Следуйте документации разработчика gRPC, чтобы создать заглушки клиента для одного из поддерживаемых языков .
  3. Вызовите метод ReportStateAndNotification .

Node.js

Клиент Google API Node.js предоставляет привязки для Home Graph API.

  1. Инициализируйте службу google.homegraph , используя учетные данные приложения по умолчанию .
  2. Вызовите метод reportStateAndNotification с помощью ReportStateAndNotificationRequest . Он возвращает Promise с 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
              }
            }
          }
        }
      }
    }
  }
});
    

Джава

Клиентская библиотека HomeGraph API для Java предоставляет привязки для Home Graph API.

  1. Инициализируйте HomeGraphApiService , используя учетные данные приложения по умолчанию .
  2. Вызовите метод reportStateAndNotification с помощью ReportStateAndNotificationRequest . Он возвращает 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);
    
Отправить полезную нагрузку последующего ответа

Полезная нагрузка для последующего ответа содержит состояние запроса, коды ошибок для сбоев событий, если применимо, и действительный followUpToken , предоставленный во время запроса намерения EXECUTE . followUpToken необходимо использовать в течение пяти минут, чтобы он оставался действительным и правильно связывал ответ с исходным запросом.

В следующем фрагменте показан пример полезных данных запроса EXECUTE с полем 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 использует followUpToken для вывода уведомления только на устройство, с которым пользователь первоначально взаимодействовал, а не для его трансляции на все устройства пользователя.

Чтобы вызвать API, выберите вариант на одной из этих вкладок:

HTTP

API Home Graph предоставляет конечную точку HTTP.

  1. Используйте загруженный файл JSON учетной записи службы, чтобы создать веб-токен JSON (JWT). Дополнительные сведения см. в разделе Аутентификация с использованием учетной записи службы .
  2. Получите токен доступа OAuth 2.0 с областью действия https://www.googleapis.com/auth/homegraph , используя oauth2l :
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Создайте запрос JSON с agentUserId . Вот пример запроса JSON для Report State и уведомления:
  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. Объедините JSON Report State и уведомления и токен в вашем запросе HTTP POST к конечной точке Google Home Graph. Вот пример того, как сделать запрос в командной строке с помощью 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

API Home Graph предоставляет конечную точку gRPC.

  1. Получите определение службы буферов протокола для API Home Graph .
  2. Следуйте документации разработчика gRPC, чтобы создать заглушки клиента для одного из поддерживаемых языков .
  3. Вызовите метод ReportStateAndNotification .

Node.js

Клиент Google API Node.js предоставляет привязки для Home Graph API.

  1. Инициализируйте службу google.homegraph , используя учетные данные приложения по умолчанию .
  2. Вызовите метод reportStateAndNotification с помощью ReportStateAndNotificationRequest . Он возвращает Promise с 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,
              }
            }
          }
        }
      }
    }
  }
});
    

Джава

Клиентская библиотека HomeGraph API для Java предоставляет привязки для Home Graph API.

  1. Инициализируйте HomeGraphApiService , используя учетные данные приложения по умолчанию.
  2. Вызовите метод reportStateAndNotification с помощью ReportStateAndNotificationRequest . Он возвращает 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);
    

Ведение журнала

Уведомления поддерживают ведение журнала событий, как описано в журналах событий Access с помощью Cloud Logging . Эти журналы полезны для тестирования и поддержания качества уведомлений в рамках вашего действия.

Ниже приведена схема записи notificationLog :

Свойство Описание
requestId Идентификатор запроса уведомления.
structName Имя структуры уведомления, например «ObjectDetection».
status Указывает статус уведомления.

Поле status включает в себя различные статусы, которые могут указывать на ошибки в полезных данных уведомления. Некоторые из них могут быть доступны только для действий, которые еще не запущены в производство.

Примеры статусов включают в себя:

Положение дел Описание
EVENT_ID_MISSING Указывает, что необходимое поле eventId отсутствует.
PRIORITY_MISSING Указывает, что поле priority отсутствует.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Указывает, что свойство notificationSupportedByAgent уведомляющего устройства, указанное в SYNC , имеет значение false.
NOTIFICATION_ENABLED_BY_USER_FALSE Указывает, что пользователь не включил уведомления на уведомляющем устройстве в GHA . Этот статус доступен только для Действий, которые не были запущены в производство.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Указывает, что пользователь не назначил уведомляющее устройство дому/структуре. Этот статус доступен только для Действий, которые не были запущены в производство.

В дополнение к этим общим статусам, которые могут применяться ко всем уведомлениям, поле status может также включать статусы, специфичные для признаков, где это применимо (например, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING ).