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

Уведомления позволяют вашей интеграции 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 и «Уведомление».

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

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

Пользователи могут выбирать, хотят ли они получать проактивные уведомления, включив эту функцию в 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 :

1. В Google Cloud Console перейдите на ключевую страницу создания сервисного аккаунта .

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

5. В списке Роль выберите Учетные записи служб > Создатель токенов учетной записи службы .

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

7. Нажмите Создать . Файл 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 ).