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 à vos utilisateurs afin qu'ils comprennent ce qui s'est passé et, si possible, comment y remédier. Réfléchissez aux scénarios d'échec possibles et à la façon 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 à un appareil hors connexion ? En planifiant ces problèmes et en aidant votre utilisateur à les résoudre, vous pouvez éviter toute frustration 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. 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'intention EXECUTE
Un utilisateur final a installé deux ampoules connectées dans son salon. L'utilisateur émet la commande "allume les lumières du salon" et Google envoie une intention 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 lumineux, 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 invite l'utilisateur avec le message "device n'est pas disponible 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'intention 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'une serrure, 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" } }] } }
Après avoir reçu la réponse, Assistant invite l'utilisateur avec le message "la batterie de l'appareil est faible".
Exemple 3 : Notifications d'erreur proactives
Dans certains cas, il peut être utile d'alerter les utilisateurs en cas d'erreur, en particulier pour les fonctions que les utilisateurs s'attendent à ce qu'elles se terminent automatiquement. Pour les traits qui acceptent les notifications proactives, vous pouvez informer l'utilisateur de manière proactive en cas d'erreur si vous avez implémenté les notifications proactives smart home.
Un sèche-linge intelligent 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 } } } } }
Le Assistant invite l'utilisateur à indiquer que la porte de l'appareil est ouverte 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 qui prennent en charge les notifications de suivi, vous pouvez envoyer une notification de suivi à l'utilisateur en cas d'erreur ou d'exception, si vous avez implémenté les smart home notifications de suivi.
Un utilisateur émet une commande pour fermer la porte de son 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 } } } } }
Le Assistant invite l'utilisateur à répondre "le dispositif 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 informations détaillées sur errorCodes, consultez la documentation de référence sur les erreurs et les exceptions.