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é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 lorsqu'il est hors connexion ? En anticipant ces problèmes et en aidant vos utilisateurs à les résoudre, vous pouvez éviter leur 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. Il é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 à répondre "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 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" } }] } }
L'Assistant Assistant invite l'utilisateur à répondre "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 à ce qu'elles s'exécutent automatiquement. Pour les caractéristiques qui acceptent les notifications proactives, vous pouvez informer l'utilisateur de manière proactive lorsqu'une erreur se produit 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 à répondre "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 lorsqu'une erreur ou une exception se produit, 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 à répondre "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.