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

Уведомления позволяют вашей интеграции 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, что уведомления на вашем устройстве включены, выполнив запрос SYNC для обновления данных устройства. Подобный запрос SYNC следует отправлять каждый раз, когда пользователи изменяют эту настройку в вашем приложении.

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

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

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

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

Отправлять запросы на уведомления в 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 ).