Notificaciones de Acciones de casa inteligente

Las notificaciones permiten que tu acción de smart home 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 hay alguien en la puerta, o para informar sobre un cambio de estado del dispositivo solicitado, como cuando se activó correctamente el cerrojo de la puerta o se trabó.

Tu acción de smart home puede enviar los siguientes tipos de notificaciones a los usuarios:

• Notificaciones proactivas: Alertan al usuario sobre un evento del dispositivo smart home sin ninguna solicitud previa del usuario a sus dispositivos, como el timbre que suena.

• Respuestas de seguimiento: Una 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, la entrega de tu acción envía una solicitud de notificación a Google. Las características del dispositivo que admite tu acción smart home determinan qué tipos de eventos de notificación están disponibles y los datos que puedes incluir en esas notificaciones.

Los siguientes atributos admiten notificaciones proactivas:

Los siguientes atributos admiten respuestas de seguimiento:

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

Compila notificaciones para tu Acción de casa inteligente

Agrega notificaciones a tu acción de smart home en estas etapas:

1. Indica a Google si las notificaciones están habilitadas desde la app de tu 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 de dispositivo.
2. Cuando se produce un evento relevante del dispositivo o un cambio de estado que activa una notificación, envía una solicitud de notificación llamando a la API de reportStateAndNotification de Report State. Si el estado del dispositivo cambió, puedes enviar un estado y una carga útil de notificación juntos en tu Report State y la llamada de 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 desean recibir notificaciones proactivas. Para ello, deben habilitar esta función en GHA. En la app de tu dispositivo smart home, también puedes agregar de manera opcional la posibilidad de que los usuarios activen o desactiven las notificaciones desde el dispositivo de forma explícita, por ejemplo, desde la configuración de la app.

Para indicarle a Google que las notificaciones están habilitadas para tu dispositivo, realiza una llamada Request 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 de tu dispositivo o si no proporcionas una opción de activación, establece la propiedad devices.notificationSupportedByAgent en true.
• Si el usuario desactivó explícitamente las notificaciones en la app de tu 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,
}]

Envía solicitudes de notificaciones a Google

Para activar notificaciones en Assistant, tu entrega 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 API de HomeGraph.

   Ve a la página de la API de HomeGraph
2. Selecciona el proyecto que coincida con el ID de tu 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 Google Cloud Console, ve a la página Crear una clave de cuenta de servicio.

   Ir a la página Crear clave de la cuenta de servicio
2. En la lista Cuenta de servicio, selecciona Cuenta de servicio nueva.
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. En la lista Función, selecciona Cuentas de servicio > Creador de tokens para cuenta de servicio.

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

7. 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 atributo del dispositivo.

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

• Cómo enviar una carga útil de notificación proactiva
• Cómo enviar 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 para las fallas del evento, si corresponde, y el followUpToken válido que se proporcionó durante la solicitud del intent EXECUTE. Se debe usar followUpToken dentro de los cinco minutos para que siga siendo válido y asocie 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 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 Accede a registros de eventos con Cloud Logging. 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 Acciones que aún no se lanzaron 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 los atributos cuando corresponda (p.ej., OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).