Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones para el hogar inteligente. Nota: Continuarás compilando acciones en la Consola de Actions.

Notificaciones de Acciones de casa inteligente

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Las notificaciones permiten que la acción 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 en el dispositivo, por ejemplo, cuando alguien está en la puerta o para informar sobre un cambio solicitado de estado del dispositivo, como cuando un cerrojo se traba o se atasca correctamente.

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

  • Notificaciones proactivas: Envía una alerta al usuario sobre un evento del dispositivo smart home sin ninguna solicitud de usuario anterior a sus dispositivos, como el timbre.

  • Respuestas de seguimiento: 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 del dispositivo que tardan en completarse.

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 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 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.

Las siguientes características admiten notificaciones proactivas:

Rasgo Eventos
ObjectDetection Objetos detectados por el dispositivo, como cuando se detecta un rostro reconocido en la puerta Por ejemplo: "Alicia y Roberto están en la puerta principal".
RunCycle El dispositivo completa un ciclo. Por ejemplo: "Se completó el ciclo de la lavadora".
SensorState El dispositivo detecta un estado de sensor compatible. Por ejemplo: "El detector de humo detecta humo".
Control de temperatura El dispositivo alcanza una temperatura establecida. Por ejemplo: "El horno se precalentó a 350 grados".
ArmArm El sistema entra en un estado previo a la alarma con una cuenta regresiva de entrada, que se activa con una puerta abierta.
Transmisión de cámara Vínculo a la transmisión en vivo de la cámara después de que el dispositivo detecte un objeto o movimiento.
MotionDetection "Se detectó movimiento a las 12 p.m. el 1 de julio de 2020".

Las siguientes características admiten respuestas de seguimiento:

Rasgo Eventos
ArmArm Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.ArmDisarm del dispositivo. Por ejemplo: "El sistema de seguridad está activado".
Bloqueo de desbloqueo Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.LockUnlock del dispositivo. Por ejemplo: "La puerta principal está trabada" o "La puerta principal está atascada".
ControlDeRed Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.TestNetworkSpeed del dispositivo. Por ejemplo: "Tu prueba de velocidad de red finalizó. La velocidad de descarga actual del router de la oficina es de 80.2 Kbps y la de carga, de 9.3 Kbps".
OpenClose. Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.OpenClose del dispositivo. Por ejemplo: "Se abrió la puerta principal" o "No se pudo abrir la puerta principal".
StartStop Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.StartStop del dispositivo. Por ejemplo: "Se encendió la aspiradora".

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

Crea notificaciones para tu Acción de casa inteligente

Agrega notificaciones a la acción smart home en estas 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 de dispositivo.
  2. Cuando ocurre un cambio de estado o evento del dispositivo relevante que activa una notificación, llama a la API de Report State reportStateAndNotification para enviar una solicitud de notificación. Si el estado del dispositivo cambió, puedes enviar el estado y la carga útil de notificación al mismo tiempo en tu Report State y llamada de notificación.

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

Indica si las notificaciones están habilitadas en tu app

Los usuarios pueden habilitar esta función en GHA para elegir si desean recibir notificaciones proactivas. En la app de tu dispositivo smart home, también puedes agregar de forma opcional la capacidad de que los usuarios activen o desactiven explícitamente 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 mediante una llamada a Request SYNC para actualizar los datos del dispositivo. Debes enviar una solicitud SYNC como la siguiente cada vez que los usuarios cambien esta 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 ofreces una opción de activación, establece la propiedad devices.notificationSupportedByAgent en true.
  • Si el usuario desactivó las notificaciones de manera explícita 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 la respuesta de SYNC:

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

Enviar solicitudes de notificación a Google

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

Habilitar la API de Google HomeGraph

  1. En Google Cloud Platform 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.

Crear una clave de cuenta de servicio

Sigue estas instrucciones para generar una clave de cuenta de servicio desde el GCP Console:

Nota: Asegúrate de usar el proyecto de GCP correcto cuando realices estos pasos. Este es el proyecto que coincide con tu ID del proyecto de smart home.
  1. En GCP Console, ve a la página Crear clave de la 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. Ingresa un nombre en el campo Nombre de cuenta de servicio.
  4. Ingresa un ID en el campo ID de cuenta de servicio.
  5. En la lista Función, 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. Se descargará a tu computadora un archivo JSON con la clave.

Enviar la notificación

Realiza la llamada a la 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 valor de 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 la 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 la característica del dispositivo.

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

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

Para llamar a la API, selecciona una de las siguientes opciones:

HTTP

La API de Home Graph proporciona un extremo HTTP.

  1. Usa el archivo JSON descargado de la cuenta de servicio para crear un token web JSON (JWT). Para obtener más información, consulta Autentica mediante una cuenta de servicio.
  2. Obtén un token de acceso de OAuth 2.0 con el permiso https://www.googleapis.com/auth/homegraph mediante oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crea la solicitud JSON con el agentUserId. Aquí hay una solicitud de JSON de muestra para Report State y una notificación:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. Combina el Report State y el JSON de la notificación y el token en tu solicitud HTTP POST al extremo de Google Home Graph. Aquí hay un ejemplo de cómo realizar la solicitud en la línea de comandos mediante curl, como una prueba:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

La API de Home Graph proporciona un extremo de gRPC.

  1. Obtén la definición del servicio de los búferes de protocolo para la API de Home Graph.
  2. Sigue la documentación de gRPC para desarrolladores a fin de generar stubs cliente para uno de los lenguajes compatibles.
  3. Llama al método ReportStateAndNotification.

Node.js

El cliente Node.js de las API de Google proporciona vinculaciones para la API de Home Graph.

  1. Inicializa el servicio google.homegraph con las credenciales predeterminadas de la aplicación.
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un Promise con el ReportStateAndNotificationResponse.
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
              }
            }
          }
        }
      }
    }
  }
});
    

Java

La biblioteca cliente de la API de HomeGraph para Java proporciona vinculaciones a la API de Home Graph.

  1. Inicializa HomeGraphApiService con las credenciales predeterminadas de la aplicación.
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un objeto ReportStateAndNotificationResponse.
// 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);
    
Enviar 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 fallas de eventos, si corresponde, y el followUpToken válido, que se proporciona durante la solicitud de intent EXECUTE. Se debe usar followUpToken en un plazo de cinco minutos para mantener la validez y asociar de forma adecuada 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 objeto followUpToken para enviar la notificación solo en el dispositivo con el que el usuario estaba interactuando originalmente, pero no para transmitirlo a todos los dispositivos del usuario.

Para llamar a la API, selecciona una de las siguientes opciones:

HTTP

La API de Home Graph proporciona un extremo HTTP.

  1. Usa el archivo JSON descargado de la cuenta de servicio para crear un token web JSON (JWT). Para obtener más información, consulta Autentica mediante una cuenta de servicio.
  2. Obtén un token de acceso de OAuth 2.0 con el permiso https://www.googleapis.com/auth/homegraph mediante oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crea la solicitud JSON con el agentUserId. Aquí hay una solicitud de JSON de muestra para Report State y una notificación:
  5. {
      "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": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. Combina el Report State y el JSON de la notificación y el token en tu solicitud HTTP POST al extremo de Google Home Graph. Aquí hay un ejemplo de cómo realizar la solicitud en la línea de comandos mediante curl, como una prueba:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

La API de Home Graph proporciona un extremo gRPC.

  1. Obtén la definición del servicio de los búferes de protocolo para la API de Home Graph.
  2. Sigue la documentación de gRPC para desarrolladores a fin de generar stubs cliente para uno de los lenguajes compatibles.
  3. Llama al método ReportStateAndNotification.

Node.js

El cliente Node.js de las API de Google proporciona vinculaciones para la API de Home Graph.

  1. Inicializa el servicio google.homegraph con las credenciales predeterminadas de la aplicación.
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un Promise con el ReportStateAndNotificationResponse.
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,
              }
            }
          }
        }
      }
    }
  }
});
    

Java

La biblioteca cliente de la API de HomeGraph para Java proporciona vinculaciones a la API de Home Graph.

  1. Inicializa HomeGraphApiService con las credenciales predeterminadas de la aplicación
  2. Llama al método reportStateAndNotification con ReportStateAndNotificationRequest. Muestra un ReportStateAndNotificationResponse
// 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);
    

Registros

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 dentro de tu acción.

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

Propiedad Descripción
requestId ID de solicitud de notificación.
structName Nombre de la estructura de notificación, como "ObjectDetection".
status Indica el estado de la notificación.

El campo status incluye varios estados que pueden indicar errores en la carga útil de la notificación. Es posible que algunas de ellas solo estén disponibles en acciones que no se lanzaron a producción.

Estos son algunos ejemplos de estados:

Estado Descripción
EVENT_ID_MISSING Indica que falta el campo eventId obligatorio.
PRIORITY_MISSING Indica que falta un campo priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indica que la propiedad notificationSupportedByAgent del dispositivo de notificación que se proporcionó en SYNC es falsa.
NOTIFICATION_ENABLED_BY_USER_FALSE Indica que el usuario no habilitó las notificaciones en el dispositivo de notificación en el GHA. Este estado solo está disponible en las acciones que no se lanzaron a producción.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indica que el usuario no asignó el dispositivo de notificación a una casa o estructura. Este estado solo está disponible en las acciones que no se lanzaron a producción.

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 la característica, si corresponde (p.ej., OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).