Lorsque des appareils ou des requêtes ne fonctionnent pas comme prévu, il est important de fournir une gestion des erreurs et une communication efficaces à vos utilisateurs afin qu'ils comprennent ce qui s'est passé et, si possible, comment corriger le problème. Assurez-vous de réfléchir aux scénarios d'échec possibles et à la manière dont votre appareil doit réagir : 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 depuis un appareil alors qu'il est hors connexion ? En anticipant ces problèmes et en aidant l'utilisateur à les résoudre, vous pouvez éviter de le frustrer et lui offrir une expérience de meilleure qualité sur vos appareils.
Ce guide fournit quelques exemples de réponses d'intent qui gèrent les erreurs. Consultez la section Erreurs et exceptions pour examiner les valeurs errorCode valides pour 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 la commande "allume les lumières de la salle de séjour" et Google envoie un intent EXECUTE à votre URL de traitement. Vous avez constaté que les appareils de l'utilisateur sont hors connexion et ne peuvent pas être contrôlés. Votre fulfillment renvoie donc une réponse EXECUTE avec status ERROR et errorCode deviceOffline.
Cet exemple montre comment renvoyer une réponse EXECUTE avec un errorCode à partir d'un appareil d'éclairage, 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 indique à l'utilisateur que "les appareils ne sont pas disponibles pour le moment" après avoir reçu la réponse. N'oubliez pas que vous devez toujours envoyer l'état hors connexion des appareils dans l'état du rapport après avoir envoyé errorCode deviceOffline dans la réponse EXECUTE.
Exemple 2 : Exception non bloquante pour l'intent EXECUTE
Un utilisateur tente de verrouiller la serrure connectée de sa porte d'entrée à l'aide de Assistant. Vous parvenez à contrôler la serrure, mais vous constatez que la batterie de l'appareil est faible. Votre traitement renvoie donc une réponse EXECUTE avec status SUCCESS et exceptionCode lowBattery.
Cet exemple montre comment envoyer une réponse EXECUTE avec un exceptionCode à partir d'un appareil de verrouillage, 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 indique à l'utilisateur que "la batterie de l'appareil est faible" 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 les fonctions que les utilisateurs s'attendent à voir s'exécuter automatiquement. Pour les caractéristiques compatibles avec les notifications proactives, vous pouvez avertir l'utilisateur de manière proactive lorsqu'une erreur se produit si vous avez implémenté les smart home notifications proactives.
Un sèche-linge connecté est en marche, et quelqu'un ouvre la porte avant la fin du cycle.
Vous pouvez appeler la méthode reportStateAndNotifications de l'API Google Home Graph pour envoyer une notification proactive avec un errorCode :
Cet exemple montre comment envoyer une notification proactive avec un 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 } } } } }
L'Assistant invite l'utilisateur à "ouvrir la porte de l'appareil" après avoir reçu la notification. Vous pouvez envoyer les états d'appareil correspondants avec les notifications dans la même charge utile.
Exemple 4 : Notification de suivi
Pour les commandes de caractéristiques compatibles avec les notifications de suivi, vous pouvez envoyer une notification de suivi à l'utilisateur lorsqu'une erreur ou une exception se produit, si vous avez implémenté les notifications de suivi smart home.
Un utilisateur donne l'ordre de fermer sa porte de garage, mais celle-ci se bloque pendant la fermeture. 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 invite l'utilisateur à "l'appareil est bloqué" après avoir reçu la notification. Vous pouvez envoyer les états d'appareil correspondants avec les notifications dans la même charge utile.
Pour en savoir plus et obtenir des errorCodes détaillés, consultez la documentation de référence sur les erreurs et exceptions.