Les notifications permettent à votre action smart home d'utiliser Google Assistant pour communiquer avec les utilisateurs au sujet d'événements ou de modifications importants liés à l'appareil. Vous pouvez implémenter des notifications pour alerter les utilisateurs en cas d'événements ponctuels sur l'appareil, par exemple lorsque quelqu'un est à la porte, ou pour signaler un changement d'état de l'appareil demandé, par exemple lorsqu'un pêne de serrure a bien été actionné ou s'est bloqué.
Votre action smart home peut envoyer les types de notifications suivants aux utilisateurs:
Notifications proactives: alerte l'utilisateur en cas d'événement sur l'appareil smart home sans qu'aucune demande préalable de l'utilisateur n'ait été envoyée sur ses appareils, telle que la sonnerie de la sonnette.
Réponses de suivi: confirmation qu'une requête de commande d'appareil a réussi ou échoué, par exemple lors du verrouillage d'une porte. Utilisez ces alertes pour les commandes d'appareil qui prennent du temps à s'exécuter. Les réponses de suivi ne sont disponibles que lorsque des requêtes de commande d'appareil sont envoyées à partir d'enceintes et d'écrans connectés.
Assistant transmet ces notifications aux utilisateurs sous forme d'annonces sur les enceintes intelligentes et les écrans connectés. Les notifications proactives sont désactivées par défaut. Les utilisateurs peuvent activer ou désactiver toutes les notifications proactives à partir de Google Home app (GHA).
Événements déclenchant des notifications
Lorsque des événements sur l'appareil se produisent, le traitement des actions envoie une demande de notification à Google. Les caractéristiques d'appareil compatibles avec votre action smart home déterminent les types d'événements de notification disponibles et les données que vous pouvez inclure dans ces notifications.
Les caractéristiques suivantes sont compatibles avec les notifications proactives:
Trait | Événements |
---|---|
ObjectDetection | Objets détectés par l'appareil, par exemple lorsqu'un visage reconnu est détecté à la porte. Par exemple: "Alice et Bob sont à la porte d'entrée." |
RunCycle | L'appareil termine un cycle. Par exemple: "Le cycle du lave-linge est terminé". |
SensorState | L'appareil détecte un état de capteur compatible. Exemple : "Le détecteur de fumée a détecté de la fumée." |
TemperatureControl | L'appareil atteint une température mémorisée. Par exemple: "Le four a été préchauffé à 350 degrés." |
ArmDisarm | Le système passe en mode de pré-alarme avec un compte à rebours à l'entrée, qui se déclenche lorsqu'une porte est ouverte. |
CameraStream | Lien vers le flux en direct de la caméra après la détection d'un objet ou d'un mouvement par l'appareil. |
MotionDetection | "Des mouvements ont été détectés à 12h le 1er juillet 2020." |
Les caractéristiques suivantes soutiennent les réponses de suivi:
Trait | Événements |
---|---|
ArmDisarm | L'état d'avancement et l'état changent après l'exécution de la commande d'appareil action.devices.commands.ArmDisarm . Par exemple : "Le système de sécurité a été activé."
|
LockUnlock | L'état d'avancement et l'état changent après l'exécution de la commande d'appareil action.devices.commands.LockUnlock . Par exemple: "La porte d'entrée a été verrouillée" ou "La porte d'entrée est bloquée."
|
NetworkControl | L'état d'avancement et l'état changent après l'exécution de la commande d'appareil action.devices.commands.TestNetworkSpeed . Par exemple: "Le test de débit de votre réseau est terminé. Le débit descendant sur le routeur du bureau est actuellement de 80,2 kbit/s et le débit ascendant de 9,3 kbit/s.
|
OpenClose | L'état d'avancement et l'état changent après l'exécution de la commande d'appareil action.devices.commands.OpenClose . Par exemple: "La porte d'entrée a été ouverte" ou "Impossible d'ouvrir la porte d'entrée."
|
StartStop | L'état d'avancement et l'état changent après l'exécution de la commande d'appareil action.devices.commands.StartStop . Par exemple: "L'aspirateur a démarré."
|
Tous les types d'appareils sont compatibles avec les notifications pour les caractéristiques applicables.
Créer des notifications pour votre action de maison connectée
Ajoutez des notifications à votre action smart home lors de ces étapes:
- Indiquez à Google si les notifications sont activées depuis l'application de votre appareil smart home. Si les utilisateurs activent ou désactivent les notifications dans votre application, envoyez une requête
SYNC
pour informer Google du changement d'appareil. - Lorsqu'un événement ou un changement d'état d'appareil pertinent se produit et qu'il déclenche une notification, envoyez une requête de notification en appelant l'API
reportStateAndNotification
Report State. Si l'état de l'appareil a changé, vous pouvez envoyer un état et une charge utile de notification ensemble dans votre Report State et votre appel de notification.
Les sections suivantes décrivent ces étapes plus en détail.
Indiquer si les notifications sont activées dans votre application
Les utilisateurs peuvent choisir de recevoir des notifications proactives en activant cette fonctionnalité dans GHA. Dans l'application de votre appareil smart home, vous pouvez également permettre aux utilisateurs d'activer/de désactiver explicitement les notifications depuis l'appareil, par exemple à partir des paramètres de votre application.
Indiquez à Google que les notifications sont activées pour votre appareil en effectuant un appel Request SYNC (Demander la synchronisation) pour mettre à jour les données de l'appareil. Vous devez envoyer une requête SYNC
comme celle-ci chaque fois que les utilisateurs modifient ce paramètre dans votre application.
Dans votre réponse SYNC
, envoyez l'une des mises à jour suivantes:
- Si l'utilisateur a explicitement activé les notifications dans l'application de votre appareil ou si vous ne proposez pas d'option d'activation, définissez la propriété
devices.notificationSupportedByAgent
surtrue
. - Si l'utilisateur a explicitement désactivé les notifications dans l'application de votre appareil, définissez la propriété
devices.notificationSupportedByAgent
surfalse
.
L'extrait de code suivant montre comment définir votre réponse SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Envoyer des demandes de notification à Google
Pour déclencher des notifications sur le Assistant, votre traitement envoie une charge utile de notification au Google Home Graph via un appel Report State et l'API Notification.
Activer l'API Google HomeGraph
-
Dans Google Cloud Console, accédez à la page API HomeGraph.
Accéder à la page de l'API HomeGraph - Sélectionnez le projet qui correspond à l'ID de votre projet smart home.
- Cliquez sur ENABLE (ACTIVER).
Créer une clé de compte de service
Suivez ces instructions pour générer une clé de compte de service à partir de Google Cloud Console:
-
Dans Google Cloud Console, accédez à la page Créer une clé de compte de service.
Accéder à la page Créer une clé de compte de service - Dans la liste Compte de service, sélectionnez Nouveau compte de service.
- Dans le champ Nom du compte de service, saisissez un nom.
- Dans le champ ID de compte de service, saisissez un ID.
Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du compte de service.
Dans le champ Type de clé, sélectionnez l'option JSON.
- Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.
Envoyer la notification
Effectuez l'appel de requête de notification à l'aide de l'API devices.reportStateAndNotification
.
Votre requête JSON doit inclure un eventId
, qui est un identifiant unique généré par votre plate-forme pour l'événement déclenchant la notification. eventId
doit être un ID aléatoire différent à chaque fois que vous envoyez une requête de notification.
Dans l'objet notifications
que vous transmettez dans votre appel d'API, incluez une valeur priority
qui définit la manière dont la notification doit être présentée. Votre objet notifications
peut inclure différents champs en fonction de la caractéristique de l'appareil.
Suivez l'un des chemins suivants pour définir la charge utile et appeler l'API:
Envoyer une charge utile de notification proactive
Pour appeler l'API, sélectionnez une option dans l'un des onglets suivants:
HTTP
L'API Home Graph fournit un point de terminaison HTTP
- Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la section S'authentifier avec un compte de service.
- Obtenez un jeton d'accès OAuth 2.0 avec le niveau d'accès
https://www.googleapis.com/auth/homegraph
à l'aide de oauth2l: - Créez la requête JSON avec le
agentUserId
. Voici un exemple de requête JSON pour Report State et Notification: - Combinez Report State, la notification JSON de notification et le jeton dans la requête HTTP POST envoyée au point de terminaison Google Home Graph. Voici un exemple d'exécution de la requête dans la ligne de commande en utilisant
curl
à des fins de test:
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
L'API Home Graph fournit un point de terminaison gRPC
- Obtenez la définition du service de tampons de protocole pour l'API Home Graph.
- Suivez la documentation gRPC destinée aux développeurs afin de générer des bouchons de client pour l'une des langues compatibles.
- Appelez la méthode ReportStateAndNotification.
Node.js
Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.
- Initialisez le service
google.homegraph
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avec ReportStateAndNotificationRequest. Elle renvoie unPromise
avec 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 bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.
- Initialisez
HomeGraphApiService
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avecReportStateAndNotificationRequest
. Elle renvoie 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);
Envoyer une charge utile de réponse de suivi
La charge utile d'une réponse de suivi contient l'état de la requête, les codes d'erreur pour les échecs d'événements, le cas échéant, et le followUpToken
valide, fourni lors de la requête d'intent EXECUTE
. L'followUpToken
doit être utilisé dans les cinq minutes pour rester valide et associer correctement la réponse à la requête d'origine.
L'extrait de code suivant montre un exemple de charge utile de requête EXECUTE
avec un champ 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 utilise le followUpToken
pour afficher la notification uniquement sur l'appareil avec lequel l'utilisateur a interagi initialement, et non sur tous ses appareils.
Pour appeler l'API, sélectionnez une option dans l'un des onglets suivants:
HTTP
L'API Home Graph fournit un point de terminaison HTTP
- Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la section S'authentifier avec un compte de service.
- Obtenez un jeton d'accès OAuth 2.0 avec le niveau d'accès
https://www.googleapis.com/auth/homegraph
à l'aide de oauth2l: - Créez la requête JSON avec le
agentUserId
. Voici un exemple de requête JSON pour Report State et Notification: - Combinez Report State, la notification JSON de notification et le jeton dans la requête HTTP POST envoyée au point de terminaison Google Home Graph. Voici un exemple d'exécution de la requête dans la ligne de commande en utilisant
curl
à des fins de test:
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
L'API Home Graph fournit un point de terminaison gRPC
- Obtenez la définition du service de tampons de protocole pour l'API Home Graph.
- Suivez la documentation gRPC destinée aux développeurs afin de générer des bouchons de client pour l'une des langues compatibles.
- Appelez la méthode ReportStateAndNotification.
Node.js
Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.
- Initialisez le service
google.homegraph
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avec ReportStateAndNotificationRequest. Elle renvoie unPromise
avec 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 bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.
- Initialisez
HomeGraphApiService
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
reportStateAndNotification
avecReportStateAndNotificationRequest
. Elle renvoie 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);
Journalisation
Les notifications sont compatibles avec la journalisation des événements, comme décrit dans Accéder aux journaux des événements avec Cloud Logging. Ces journaux sont utiles pour tester et maintenir la qualité des notifications au sein de votre action.
Voici le schéma d'une entrée notificationLog
:
Propriété | Description |
---|---|
requestId |
ID de la demande de notification. |
structName |
Nom de la structure de notification, tel que "ObjectDetection". |
status |
Indique l'état de la notification. |
Le champ status
inclut différents états pouvant indiquer des erreurs dans la charge utile de la notification. Il est possible que certains d'entre eux ne soient disponibles que pour les actions qui n'ont pas été lancées en production.
Voici quelques exemples d'états:
État | Description |
---|---|
EVENT_ID_MISSING |
Indique que le champ obligatoire eventId est manquant.
|
PRIORITY_MISSING |
Indique qu'un champ priority est manquant.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Indique que la propriété notificationSupportedByAgent de l'appareil à l'origine de la notification fournie dans SYNC est "false".
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Indique que l'utilisateur n'a pas activé les notifications sur l'appareil à l'origine de la notification dans GHA. Cet état n'est disponible que pour les actions qui ne sont pas passées en production. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Indique que l'utilisateur n'a pas attribué l'appareil à l'origine de la notification à une maison/structure. Cet état n'est disponible que pour les actions qui ne sont pas passées en production. |
En plus des états généraux qui peuvent s'appliquer à toutes les notifications, le champ status
peut également inclure des états spécifiques à chaque caractéristique, le cas échéant (par exemple, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).