Notificaciones de Acciones de casa inteligente

Las notificaciones permiten que se use tu acción de smart home Google Assistant para comunicarte con los usuarios eventos o cambios relacionados con el dispositivo. Puedes implementar notificaciones para alertar a los usuarios a eventos puntuales del dispositivo, por ejemplo, cuando hay alguien en la puerta o generar informes sobre un cambio de estado del dispositivo solicitado, como cuando el cerrojo de una cerradura de puerta si se comprometió o se atascó.

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

• Notificaciones proactivas: Alerta al usuario sobre un evento de smart home. evento de dispositivo sin ninguna solicitud anterior del usuario a sus dispositivos, como cuando suene el timbre.

• Respuestas de seguimiento: una confirmación de que una solicitud de comando de dispositivo correctamente o no, por ejemplo, al trabar una puerta. Usar estas alertas para comandos del dispositivo que tardan en completarse. Las respuestas de seguimiento solo son compatible cuando las solicitudes de comando del dispositivo se envían desde bocinas y dispositivos pantallas.

Assistant proporciona estas notificaciones a los usuarios como anuncios en bocinas y pantallas inteligentes. 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 ocurren eventos en el dispositivo, la entrega de Acciones envía una solicitud de notificación a Google. Las características del dispositivo de las que tu acción smart home determina qué tipos de eventos de notificación están disponibles y la datos que puedes incluir en esas notificaciones.

Las siguientes características admiten notificaciones proactivas:

Las siguientes características admiten respuestas de seguimiento:

Todos los tipos de dispositivo admiten notificaciones de las características aplicables.

Cómo crear notificaciones para tu Acción de casa inteligente

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

1. Indícale a Google si las notificaciones están habilitadas desde tu smart home app para dispositivos. 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 relevante del dispositivo o un cambio de estado que activa una notificación, envía una solicitud de notificación llamando al API de Report State reportStateAndNotification. Si el botón cambió el estado del dispositivo, puedes enviar un estado y una carga útil de notificaciones en tu llamada a Report State y a las de notificaciones.

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 habilitando esta función en GHA. En la app de tu dispositivo smart home, también puedes agregar de manera opcional la capacidad de usuarios para activar o desactivar de manera 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 haciendo una llamada a Request SYNC para actualizar los datos del dispositivo. Debes enviar una solicitud SYNC como esta cada vez que los usuarios cambian 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 tienes la opción de activar o desactivar, configura propiedad devices.notificationSupportedByAgent a true.
• Si el usuario desactivó explícitamente las notificaciones en la app del dispositivo, configura la propiedad devices.notificationSupportedByAgent a 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 de entrega envía una carga útil de notificación al Google Home Graph a través de un Report State y una llamada a la API de Notification.

Cómo habilitar la API de Google HomeGraph

1. En Google Cloud Console, ve a la página 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 Google Cloud Console:

1. En Google Cloud Console, ve a la página Crear clave de cuenta de servicio.

   Ir a la página Crear clave de la cuenta de servicio
2. Desde 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 la cuenta de servicio, ingresa un ID.

5. Desde la lista de Rol, selecciona Cuentas de servicio > Creador de tokens de cuenta de servicio.

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

7. Haz clic en Crear. Un archivo JSON que contiene tu clave descargas en tu computadora.

Envía la notificación

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

En el objeto notifications que pasas en la llamada a la API, incluye un Es el valor de priority que define cómo se debe presentar la notificación. Tu El objeto notifications puede incluir diferentes campos según el dispositivo. de la aplicación.

Sigue una de estas rutas para configurar 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

Enviar 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, el error de fallas de eventos, si corresponde, y el followUpToken válido que se proporciona durante la solicitud de intent EXECUTE. Se debe usar el followUpToken en un plazo de cinco minutos para mantener la validez y asociar correctamente la respuesta con la solicitud original.

En el siguiente fragmento, se muestra un ejemplo de carga útil de solicitud EXECUTE con una 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 enviar la notificación solo en el dispositivo. con el que el usuario estaba interactuando originalmente, y no a través de todas las en los dispositivos del usuario.

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 los 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 el de notificación. Es posible que algunas solo estén disponibles en Acciones que tengan no se lanzó 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 características cuando corresponda (p.ej., OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).