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

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

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

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

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

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

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

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

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

Следующие характеристики способствуют получению последующих ответов:

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

Создавайте уведомления для вашей интеграции между облачными сервисами.

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

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

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

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

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

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

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

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

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

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

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

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

Включите API Google HomeGraph

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

   Перейдите на страницу API HomeGraph.
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. В поле « Тип ключа» выберите вариант 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);
    

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

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

Ниже представлена ​​схема записи в файле notificationLog :

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

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

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