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 alguien está en la puerta, o para informar sobre un cambio de estado del dispositivo solicitado, como cuando el cerrojo de la cerradura de la puerta se trabó o se trabó con éxito.
Tu acción smart home puede enviar los siguientes tipos de notificaciones a los usuarios:
Notificaciones proactivas: Alerta al usuario sobre un evento del dispositivo smart home sin ninguna solicitud previa a sus dispositivos, como el sonido del timbre.
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 tarden en completarse. Las respuestas de seguimiento solo se admiten cuando las solicitudes de comando 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 el Google Home app (GHA).
Eventos que activan notificaciones
Cuando se producen eventos en el dispositivo, la entrega de Actions 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 que detecta 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". |
TemperatureControl | El dispositivo alcanza un punto de ajuste de temperatura. Por ejemplo: "Se precalentó el horno a 350 grados". |
ArmDisarm | El sistema entra en un estado de alarma previa con una cuenta regresiva de entrada que se activa cuando una puerta abierta. |
CameraStream | Se vincula a la transmisión en vivo de la cámara después de que el dispositivo detecta un objeto o un movimiento. |
MotionDetection | "Se detectó movimiento el 1 de julio de 2020 a las 12 p.m.". |
Las siguientes características admiten respuestas de seguimiento:
Rasgo | Eventos |
---|---|
ArmDisarm | Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.ArmDisarm del dispositivo. Por ejemplo:
"Se activó el sistema de seguridad".
|
LockUnlock | Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.LockUnlock del dispositivo. Por ejemplo: "Se trabó la puerta principal" o "La puerta principal está atascada".
|
NetworkControl | Estado de finalización y cambio de estado después de la ejecución del comando action.devices.commands.TestNetworkSpeed del dispositivo. Por ejemplo: "Finalizó la prueba de velocidad de red. La velocidad actual de descarga del router de la oficina es de 80.2 Kbps y la velocidad de carga es 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 inició la aspiradora".
|
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:
- Indícale 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 del cambio en el dispositivo. - 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.
Indícale 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 esta 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 proporcionas una opción de activación, establece la propiedad
devices.notificationSupportedByAgent
entrue
. - Si el usuario desactivó las notificaciones de manera explícita en la app del dispositivo, establece la propiedad
devices.notificationSupportedByAgent
enfalse
.
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 Assistant, tu entrega envía una carga útil de notificación al Google Home Graph a través de una Report State y una llamada a la API de Notification.
Cómo habilitar la API de Google HomeGraph
-
En Google Cloud Console, ve a la página API de HomeGraph.
Ir a la página de la API de HomeGraph - Selecciona el proyecto que coincida con tu ID del proyecto de smart home.
- 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:
-
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 - En la lista Cuenta de servicio, selecciona Nueva cuenta de servicio.
- Escribe un nombre en el campo Nombre de cuenta de servicio.
- En el campo ID de la cuenta de servicio, ingresa un ID.
En la lista Función, selecciona Cuentas de servicio > Creador de tokens para cuenta de servicio.
En Tipo de clave, selecciona la opción JSON.
- 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 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:
Enviar una carga útil de notificación proactiva
Para llamar a la API, selecciona una opción de una de estas pestañas:
HTTP
La API de Home Graph proporciona un extremo HTTP
- Usa el archivo JSON de la cuenta de servicio que descargaste para crear un token web JSON (JWT). Para obtener más información, consulta Autenticación con una cuenta de servicio.
- Obtén un token de acceso de OAuth 2.0 con el permiso
https://www.googleapis.com/auth/homegraph
mediante oauth2l: - Crea la solicitud JSON con el
agentUserId
. A continuación, se muestra un ejemplo de una solicitud JSON para Report State y notificación: - Combina el Report State y el JSON de notificación, y el token de tu solicitud HTTP POST al extremo de Google Home Graph. A continuación, se muestra un ejemplo de cómo realizar la solicitud en la línea de comandos con
curl
como prueba:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
- Obtén la definición del servicio de búferes de protocolo para la API de Home Graph.
- Sigue la documentación para desarrolladores de gRPC con el objetivo de generar stubs de cliente para uno de los lenguajes compatibles.
- Llama al método ReportStateAndNotification.
Node.js
El cliente de Node.js de las APIs de Google proporciona vinculaciones para la API de Home Graph.
- Inicializa el servicio
google.homegraph
con las credenciales predeterminadas de la aplicación. - Llama al método
reportStateAndNotification
con ReportStateAndNotificationRequest. Muestra unPromise
con 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 para la API de Home Graph.
- Inicializa
HomeGraphApiService
con las credenciales predeterminadas de la aplicación. - Llama al método
reportStateAndNotification
conReportStateAndNotificationRequest
. Muestra unReportStateAndNotificationResponse
.
// 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 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 mantener su 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 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 emitir la notificación solo en el dispositivo con el que el usuario interactuó originalmente y no la transmite en todos los dispositivos del usuario.
Para llamar a la API, selecciona una opción de una de estas pestañas:
HTTP
La API de Home Graph proporciona un extremo HTTP
- Usa el archivo JSON de la cuenta de servicio que descargaste para crear un token web JSON (JWT). Para obtener más información, consulta Autenticación con una cuenta de servicio.
- Obtén un token de acceso de OAuth 2.0 con el permiso
https://www.googleapis.com/auth/homegraph
mediante oauth2l: - Crea la solicitud JSON con el
agentUserId
. A continuación, se muestra un ejemplo de una solicitud JSON para Report State y notificación: - Combina el Report State y el JSON de notificación, y el token de tu solicitud HTTP POST al extremo de Google Home Graph. A continuación, se muestra un ejemplo de cómo realizar la solicitud en la línea de comandos con
curl
como prueba:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
- Obtén la definición del servicio de búferes de protocolo para la API de Home Graph.
- Sigue la documentación para desarrolladores de gRPC con el objetivo de generar stubs de cliente para uno de los lenguajes compatibles.
- Llama al método ReportStateAndNotification.
Node.js
El cliente de Node.js de las APIs de Google proporciona vinculaciones para la API de Home Graph.
- Inicializa el servicio
google.homegraph
con las credenciales predeterminadas de la aplicación. - Llama al método
reportStateAndNotification
con ReportStateAndNotificationRequest. Muestra unPromise
con 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 para la API de Home Graph.
- Inicializa
HomeGraphApiService
con las credenciales predeterminadas de la aplicación - Llama al método
reportStateAndNotification
conReportStateAndNotificationRequest
. Muestra unReportStateAndNotificationResponse
.
// 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 dentro de tu acción.
El siguiente es el esquema de una entrada notificationLog
:
Propiedad | Descripción |
---|---|
requestId |
ID de solicitud de notificación. |
structName |
Nombre de la struct 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 obligatorio eventId .
|
PRIORITY_MISSING |
Indica que falta un campo priority .
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Indica que la propiedad notificationSupportedByAgent del dispositivo que envía la notificación proporcionada en SYNC es falsa.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Indica que el usuario no habilitó las notificaciones en el dispositivo que las envía en 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 que envía la 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 características cuando corresponda (p.ej., OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).