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ó o se destrabó correctamente.

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

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

• Respuestas de seguimiento: Es una confirmación de que una solicitud de comando del dispositivo se realizó correctamente o falló, por ejemplo, cuando se bloquea una puerta. Usa estas alertas para los comandos de dispositivos 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 inteligentes y pantallas inteligentes. Las notificaciones proactivas están desactivadas de forma predeterminada. Los usuarios pueden activar o desactivar todas las notificaciones proactivas desde la Google Home app (GHA).

Eventos que activan notificaciones

Cuando se producen eventos de dispositivo, tu entrega envía una solicitud de notificación a Google. Los atributos de 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 rasgos aplicables.

Cómo compilar notificaciones para tu integración de nube a nube

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

1. Indica a Google si las notificaciones están habilitadas desde tu app para dispositivos de 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 de dispositivo.
2. Cuando se produce un evento de dispositivo o un cambio de estado pertinente que activa una notificación, envía una solicitud de notificación llamando a la API de Report State reportStateAndNotification. Si el estado del dispositivo cambió, puedes enviar una carga útil de estado y de notificación juntas en tu llamada de Report State y notificación.

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 de que los usuarios activen o desactiven de forma explícita las notificaciones del dispositivo, por ejemplo, desde la configuración de la app.

Indica a Google que las notificaciones están habilitadas para tu dispositivo realizando una llamada de solicitud de SYNC 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 SYNC, envía una de estas actualizaciones:

• Si el usuario activó explícitamente las notificaciones en la app para dispositivos o si no proporcionas una opción de activar y desactivar, establece la propiedad devices.notificationSupportedByAgent en true.
• Si el usuario desactivó explícitamente las notificaciones en la app para dispositivos, 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,
}]

Envía solicitudes de notificación a Google

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

Habilita la API de Google HomeGraph

1. En la 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 de 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 la 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 dirija 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 de la lista de cuentas de servicio y elige 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á en tu computadora un archivo JSON que contiene tu 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 de 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 de eventos, si corresponde, y el followUpToken válido, proporcionado durante la solicitud de intent EXECUTE. El followUpToken se debe usar en un plazo de cinco minutos para que siga siendo válido y para 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 el followUpToken para mostrar la notificación solo en el dispositivo con el que el usuario interactuaba originalmente y no transmitirla a todos sus dispositivos.

Para llamar a la API, selecciona una opción de 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 Cloud-to-cloud. Estos registros son útiles para probar y mantener la calidad de las notificaciones en tu Acción.

El siguiente es el esquema de una entrada 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 solo estén disponibles en las acciones que no se hayan lanzado a 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 de rasgos cuando corresponda (por ejemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).