Lorsque des appareils ou des requêtes ne fonctionnent pas comme prévu, il est important de fournir une bonne gestion des erreurs et une bonne communication pour vos utilisateurs afin qu’ils comprennent et, dans la mesure du possible, comment le corriger. Assurez-vous de réfléchir à les scénarios de défaillance possibles et la réaction de l'appareil. Que se passe-t-il si un utilisateur interrompt une tâche en cours ? Que se passe-t-il si un utilisateur demande une action à partir d'un appareil ? lorsqu'il est hors connexion ? Planifier ces problèmes et aider les utilisateurs à s'en remettre peuvent éviter la frustration des utilisateurs et créer une expérience de meilleure qualité pour vos appareils.
Ce guide fournit quelques exemples de réponses d'intent qui gèrent les erreurs. Voir
la section Erreurs et exceptions pour
Vérifiez les valeurs errorCode valides pour identifier les erreurs et les exceptions.
Exemple 1: Réponse d'erreur pour l'intent EXECUTE
Un utilisateur final a installé deux ampoules connectées dans son salon. L'utilisateur
émet une commande "allume les lumières du salon" et Google a envoyé un EXECUTE
vers votre URL de traitement. Vous avez constaté que les appareils de l'utilisateur sont hors connexion
et non contrôlable. Par conséquent, votre fulfillment renvoie une réponse EXECUTE avec
status ERROR et errorCode deviceOffline.
Cet exemple montre comment renvoyer une réponse EXECUTE avec une
errorCode à partir d'un appareil léger, comme décrit précédemment:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "light-device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "light-device-id-2" ], "status": "ERROR", "errorCode": "deviceOffline" } ] } }
Google Assistant affichera une invite indiquant que les appareils sont
actuellement indisponible." après avoir reçu la réponse. N'oubliez pas que vous
doivent envoyer l'état hors connexion pour les appareils en état de signalement après l'envoi
errorCode deviceOffline dans la réponse EXECUTE.
Exemple 2: Exception non bloquante pour l'intent EXECUTE
Un utilisateur essaie de verrouiller sa serrure connectée à la porte d'entrée en utilisant un appareil avec
Assistant Vous pouvez contrôler avec
succès sa serrure, mais
vous constatez que la batterie de l'appareil est faible, donc votre traitement renvoie un EXECUTE
réponse avec status SUCCESS et exceptionCode lowBattery.
Cet exemple montre comment envoyer une réponse EXECUTE avec une
exceptionCode sur un appareil verrouillé, comme décrit précédemment:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["lock-device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
Assistant affichera une invite indiquant que l'appareil a une faible de batterie" après avoir reçu la réponse.
Exemple 3: Notifications d'erreur proactives
Dans certains cas, il peut être utile d'alerter les utilisateurs d'une erreur, en particulier pour que les utilisateurs s'attendent à exécuter automatiquement. Pour les caractéristiques qui notifications proactives, vous pouvez avertir l'utilisateur de manière proactive pendant qu'un une erreur se produit si vous avez implémenté smart home notifications proactives.
Un sèche-linge connecté est en cours, et quelqu'un ouvre la porte avant la fin du cycle.
Vous pouvez appeler l'API Google Home Graph
reportStateAndNotifications pour envoyer une notification proactive avec une
errorCode:
Cet exemple montre comment envoyer une notification proactive avec une
errorCode à partir d'un sèche-linge, comme décrit précédemment:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
Assistant enverra une invite indiquant que la porte de l'appareil est ouvert" après avoir reçu la notification. Vous pouvez envoyer les réponses états de l'appareil avec les notifications dans la même charge utile.
Exemple 4: Notification de suivi
Pour les commandes de traits compatibles avec les notifications de suivi, vous pouvez envoyer une notification de suivi à l'utilisateur lors d'une erreur ou d'une exception, vous avez implémenté smart home notifications de suivi.
Un utilisateur ordonne à l'utilisateur de fermer sa porte de garage, mais celle-ci est bloquée
lors de la clôture. Vous pouvez envoyer une notification de suivi avec un errorCode:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "door-device-id": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "follow-up-token-1" } } } }, "states": { "door-device-id": { "openPercent": 70 } } } } }
Assistant affichera une invite indiquant que l'appareil est bloquée" après avoir reçu la notification. Vous pouvez envoyer les réponses états des appareils avec des notifications dans la même charge utile.
Pour obtenir plus d'informations et des informations détaillées sur errorCodes, consultez les
Erreurs et exceptions
documentation de référence.