Lorsque les appareils ou les 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, dans la mesure du possible, comment y remédier. Veillez à réfléchir aux scénarios de défaillance possibles et à la manière dont votre appareil réagira. 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 alors qu'il est hors connexion ? En prévoyant ces problèmes et en aidant votre utilisateur à se remettre d'une telle situation, vous éviterez de la décevoir et vous créerez une expérience de meilleure qualité sur vos appareils.
Ce guide fournit des 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 possède deux systèmes d'éclairage connectés et est installé dans son salon. L'utilisateur exécute la commande "allume les lumières du salon" et Google a envoyé un intent EXECUTE à votre URL de traitement. Vous avez constaté que les appareils de l'utilisateur sont hors connexion et qu'ils ne peuvent pas être contrôlés. Par conséquent, votre traitement renvoie 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 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 affiche à l'utilisateur le message "device are not available right now" après avoir reçu la réponse. N'oubliez pas que vous devez toujours envoyer l'état hors connexion des appareils en état de 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 sa serrure connectée à la porte d'entrée à l'aide d'un appareil avec Assistant. Vous pouvez contrôler le verrouillage, 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 affichera le message "L'appareil a une batterie 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 qu'ils souhaitent exécuter automatiquement. Pour les fonctionnalités compatibles avec les notifications proactives, vous pouvez avertir l'utilisateur de manière proactive en cas d'erreur si vous avez implémenté les notifications proactives smart home.
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 depuis 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 affichera à l'utilisateur le message "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 compatibles avec 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 notifications de suivi smart home.
Un utilisateur émet une commande pour fermer sa porte de garage, mais celle-ci est bloquée lors de la fermeture. Vous pouvez envoyer une notification de suivi avec une 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 le message "L'appareil est bloqué" après avoir reçu la notification. Vous pouvez envoyer les états correspondants de l'appareil avec des notifications dans la même charge utile.
Pour en savoir plus sur errorCodes, consultez la documentation de référence sur les erreurs et exceptions.