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

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

Интеграция Cloud-to-cloud может отправлять пользователям следующие типы уведомлений:

• Проактивные уведомления. Уведомления о smart homeсобытиях на устройстве, которые не были вызваны запросами пользователя, например о звонке в дверь.

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

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

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

Когда происходят события на устройстве, ваше решение отправляет в Google запрос на уведомление. От того, какие характеристики устройства поддерживает интеграция Cloud-to-cloud, зависит, какие типы событий доступны для уведомлений и какие данные можно в них включать.

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

Поддерживаются следующие черты:

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

Как создавать уведомления для интеграции облачных сервисов

Добавьте уведомления в интеграцию Cloud-to-cloud на следующих этапах:

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

Ниже вы найдете подробное описание этих шагов.

Как указать, включены ли уведомления в приложении

Пользователи могут включить эту функцию в разделе 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 с помощью вызова API Report State и уведомлений.

Как включить Google HomeGraph API

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

   Перейти на страницу HomeGraph API
2. Выберите проект, соответствующий идентификатору проекта smart home.
3. Нажмите Включить.

Как создать ключ сервисного аккаунта

Чтобы создать ключ сервисного аккаунта в Google Cloud Console, выполните следующие действия:

1. В Google Cloud Console перейдите на страницу Сервисные аккаунты.

   Перейдите на страницу "Сервисные аккаунты".

   Возможно, вам потребуется выбрать проект, прежде чем вы перейдете на страницу "Сервисные аккаунты".

2. Нажмите addСоздать сервисный аккаунт.

3. В поле Название сервисного аккаунта введите название.

4. В поле Идентификатор сервисного аккаунта введите идентификатор.

5. В поле Описание сервисного аккаунта введите описание.

6. Нажмите кнопку Создать и продолжить.

7. В раскрывающемся списке Роль выберите Сервисные аккаунты > Создатель токена идентификации OpenID Connect сервисного аккаунта.

8. Нажмите Продолжить.

9. Нажмите Готово.

10. Выберите созданный сервисный аккаунт из списка и нажмите Управление ключами в меню more_vert Действия.

11. Нажмите Добавить ключ > Создать ключ.

12. В поле Key type (Тип ключа) выберите JSON.

13. Нажмите Создать. На ваш компьютер будет скачан JSON-файл с ключом.

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

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

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

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

• Как отправить полезную нагрузку для проактивного уведомления
• Как отправить полезную нагрузку для последующего ответа

Как отправить полезную нагрузку для проактивного уведомления

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

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);
    

Как отправить полезную нагрузку для последующего ответа

Полезная нагрузка для последующего ответа содержит статус запроса, коды ошибок для сбоев событий (если применимо) и действительный 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, выберите вариант на одной из следующих вкладок:

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);
    

Журналы

Уведомления поддерживают ведение журнала событий, как описано в разделе Ведение журнала Cloud-to-Cloud. Эти журналы полезны для тестирования и поддержания качества уведомлений в вашем действии.

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

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

Примеры статусов:

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