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 résoudre le problème. Réfléchissez aux scénarios d'échec possibles et à la manière dont votre appareil doit répondre : 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 lorsqu'il est hors connexion ? En planifiant ces problèmes et en aidant votre utilisateur à les résoudre, vous pouvez éviter sa frustration et offrir 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'intent EXECUTE
Un utilisateur final a installé deux lumières connectées dans son salon. L'utilisateur émet la commande "Allume les lumières du salon" et Google envoie un intent EXECUTE à votre URL de traitement. Vous constatez que les appareils de l'utilisateur sont hors connexion et ne peuvent pas être contrôlés. Votre traitement 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" } ] } }
Le Google Assistant invite l'utilisateur à indiquer que l'appareil 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'intent EXECUTE
Un utilisateur tente de verrouiller la serrure connectée de sa porte d'entrée à l'aide de
Assistant. Vous pouvez contrôler sa 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" } }] } }
Le Assistant invite l'utilisateur à indiquer 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 en cas d'erreur, en particulier pour les fonctions que les utilisateurs s'attendent à effectuer automatiquement. Pour les caractéristiques qui acceptent les notifications proactives, vous pouvez informer l'utilisateur de manière proactive en cas d' erreur si vous avez implémenté smart home des 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 Google Home Graph API
reportStateAndNotifications méthode 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 acceptent 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é smart home des notifications de suivi.
Un utilisateur émet une commande pour fermer la porte de son garage, mais la porte se bloque lors de 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 à indiquer que 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
Erreurs et exceptions.