Notificaciones de Acciones de casa inteligente

Las notificaciones permiten que tu integración de Cloud-to-cloud use Google Assistant para comunicarse con los usuarios sobre eventos o cambios importantes relacionados con el dispositivo. Puedes implementar notificaciones para alertar a los usuarios sobre eventos oportunos del dispositivo, por ejemplo, cuando alguien está en la puerta, o para informar sobre un cambio de estado solicitado del dispositivo, como cuando el cerrojo de una puerta se trabó correctamente o se atascó.

Tu integración de Cloud-to-cloud puede enviar los siguientes tipos de notificaciones a los usuarios:

• Notificaciones proactivas: Alertan al usuario sobre un evento del dispositivo smart home sin que haya solicitudes previas del usuario a sus dispositivos, como el timbre de la puerta.

• Respuestas de seguimiento: Confirmación de que una solicitud de comando del dispositivo se realizó correctamente o falló, por ejemplo, cuando se traba una puerta. Usa estas alertas para los comandos del dispositivo que tardan en completarse. Las respuestas de seguimiento solo se admiten cuando las solicitudes de comandos del dispositivo se envían desde bocinas y pantallas inteligentes.

Assistant proporciona estas notificaciones a los usuarios como anuncios en bocinas y pantallas inteligentes. Las notificaciones proactivas están desactivadas de forma predeterminada. Los usuarios pueden activar o desactivar todas las notificaciones proactivas desde Google Home app (GHA).

Eventos que activan notificaciones

Cuando ocurren eventos del dispositivo, tu cumplimiento envía una solicitud de notificación a Google. Los rasgos del dispositivo que admite tu integración de Cloud-to-cloud determinan qué tipos de eventos de notificación están disponibles y los datos que puedes incluir en esas notificaciones.

Los siguientes rasgos admiten notificaciones proactivas:

Los siguientes rasgos admiten respuestas de seguimiento:

Todos los tipos de dispositivos admiten notificaciones para los traits aplicables.

Crea notificaciones para tu integración de nube a nube

Agrega notificaciones a tu integración de Cloud-to-cloud en las siguientes etapas:

1. Indica a Google si las notificaciones están habilitadas desde la app del dispositivo smart home. Si los usuarios activan o desactivan las notificaciones en tu app, envía una solicitud SYNC para informar a Google sobre el cambio en el dispositivo.
2. Cuando se produce un evento o un cambio de estado del dispositivo relevante que activa una notificación, llama a la API de Report State reportStateAndNotification para enviar una solicitud de notificación. Si cambió el estado del dispositivo, puedes enviar una carga útil de estado y de notificación juntas en tu llamada de Report State y Notification.

En las siguientes secciones, se describen estos pasos con más detalle.

Indica si las notificaciones están habilitadas en tu app

Los usuarios pueden elegir si quieren recibir notificaciones proactivas habilitando esta función en GHA. En la app para tu dispositivo smart home, también puedes agregar, de forma opcional, la capacidad para que los usuarios activen o desactiven explícitamente las notificaciones del dispositivo, por ejemplo, desde la configuración de tu app.

Indica a Google que las notificaciones están habilitadas para tu dispositivo realizando una llamada de SOLICITUD DE SINCRONIZACIÓN para actualizar los datos del dispositivo. Debes enviar una solicitud SYNC como esta cada vez que los usuarios cambien este parámetro de configuración en tu app.

En tu respuesta de SYNC, envía una de estas actualizaciones:

• Si el usuario activó explícitamente las notificaciones en la app del dispositivo o si no proporcionas una opción para activarlas, establece la propiedad devices.notificationSupportedByAgent en true.
• Si el usuario desactivó explícitamente las notificaciones en la app del dispositivo, establece la propiedad devices.notificationSupportedByAgent en false.

En el siguiente fragmento, se muestra un ejemplo de cómo configurar tu respuesta de SYNC:

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

Enviar solicitudes de notificación a Google

Para activar notificaciones en Assistant, tu cumplimiento envía una carga útil de notificación a Google Home Graph a través de una llamada a la API de Report State y Notification.

Habilita la API de Google HomeGraph

1. En Google Cloud Console, ve a la página de la API de HomeGraph.

   Ir a la página de la API de HomeGraph
2. Selecciona el proyecto que coincida con tu ID del proyecto smart home.
3. Haz clic en HABILITAR.

Crea una clave de cuenta de servicio

Sigue estas instrucciones para generar una clave de cuenta de servicio desde Google Cloud Console:

1. En la Google Cloud Console, ve a la página Cuentas de servicio.

   Ir a la página Cuentas de servicio

   Es posible que debas seleccionar un proyecto antes de que se te redireccione a la página Cuentas de servicio.

2. Haz clic en addCrear cuenta de servicio.

3. Escribe un nombre en el campo Nombre de cuenta de servicio.

4. En el campo ID de cuenta de servicio, ingresa un ID.

5. Opcional: en el campo Descripción de la cuenta de servicio, escribe una descripción.

6. Haz clic en Crear y continuar.

7. En el menú desplegable Rol, selecciona Cuentas de servicio > Creador de tokens de identidad de OpenID Connect para cuentas de servicio.

8. Haz clic en Continuar.

9. Haz clic en Listo.

10. Selecciona la cuenta de servicio que acabas de crear en la lista de cuentas de servicio y, luego, selecciona Administrar claves en el menú more_vert Acciones.

11. Selecciona Agregar clave > Crear clave nueva.

12. En Tipo de clave, selecciona la opción JSON.

13. Haz clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.

Envía la notificación

Realiza la llamada de solicitud de notificación con la API de devices.reportStateAndNotification. Tu solicitud JSON debe incluir un eventId, que es un ID único que genera tu plataforma para el evento que activa la notificación. El eventId debe ser un ID aleatorio que sea diferente cada vez que envíes una solicitud de notificación.

En el objeto notifications que pasas en tu llamada a la API, incluye un valor priority que defina cómo se debe presentar la notificación. Tu objeto notifications puede incluir diferentes campos según el rasgo del dispositivo.

Sigue una de estas rutas para establecer la carga útil y llamar a la API:

• Envía una carga útil de notificación proactiva
• Envía una carga útil de respuesta de seguimiento

Envía una carga útil de notificación proactiva

Para llamar a la API, selecciona una opción en una de estas pestañas:

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

Envía una carga útil de respuesta de seguimiento

La carga útil de una respuesta de seguimiento contiene el estado de la solicitud, los códigos de error de las fallas del evento (si corresponde) y el followUpToken válido, que se proporciona durante la solicitud de intención EXECUTE. El followUpToken debe usarse en un plazo de cinco minutos para seguir siendo válido y asociar correctamente la respuesta con la solicitud original.

En el siguiente fragmento, se muestra un ejemplo de carga útil de solicitud EXECUTE con un campo 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 usa followUpToken para generar la notificación solo en el dispositivo con el que el usuario interactuó originalmente y no para transmitirla a todos los dispositivos del usuario.

Para llamar a la API, selecciona una opción en una de estas pestañas:

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

Logging

Las notificaciones admiten el registro de eventos, como se describe en Cloud Logging para la integración de nube a nube. Estos registros son útiles para probar y mantener la calidad de las notificaciones en tu Acción.

A continuación, se muestra el esquema de una entrada de notificationLog:

El campo status incluye varios estados que pueden indicar errores en la carga útil de la notificación. Es posible que algunas de estas opciones solo estén disponibles en las Acciones que no se hayan lanzado en producción.

Estos son algunos ejemplos de estados:

Además de estos estados generales que se pueden aplicar a todas las notificaciones, el campo status también puede incluir estados específicos del rasgo cuando corresponda (por ejemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).