Lorsque les appareils ou les requêtes ne fonctionnent pas comme prévu, il est important de fournir une bonne gestion des erreurs et de communiquer à vos utilisateurs afin qu'ils comprennent ce qui s'est passé et, dans la mesure du possible, comment y remédier. Réfléchissez aux scénarios de défaillance possibles et à la manière dont votre appareil va 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 hors connexion ? En anticipant la résolution de ces problèmes et en aidant les utilisateurs à les résoudre, vous évitez les frustrations des utilisateurs et leur offrez une meilleure expérience 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 dispose de deux ampoules connectées et est installé dans le salon. L'utilisateur envoie une 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 ne peuvent pas être contrôlés. Par conséquent, votre fulfillment renvoie une réponse EXECUTE avec status ERROR et errorCode deviceOffline.
Cet exemple montre comment renvoyer une réponse EXECUTE avec une réponse 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 will prompt the user with "the device are
not available right now" after receiving the response. Remember that you still
need to send offline state for devices in report state after sending
errorCode deviceOffline in EXECUTE response.
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 leur verrouillage, mais vous constatez que la batterie de l'appareil est faible. Votre fulfillment renvoie donc une réponse EXECUTE avec status SUCCESS et exceptionCode lowBattery.
Cet exemple montre comment envoyer une réponse EXECUTE avec une exceptionCode depuis 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 demandera à l'utilisateur "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 que les utilisateurs souhaitent terminer automatiquement. Pour les caractéristiques qui acceptent les notifications proactives, vous pouvez avertir l'utilisateur de manière proactive en cas d'erreur si vous avez implémenté smart home proactive notifications..
Un sèche-linge intelligent est en marche, et quelqu'un ouvre la porte avant la fin du cycle.
Vous pouvez appeler Google Home Graph API
reportStateAndNotifications method to send a proactive notification with an
errorCode:
Cet exemple montre comment envoyer une notification proactive avec un errorCode depuis un appareil de séchage 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
}
}
}
}
}
Lorsque Assistantla porte de l'appareilest ouverte, un message s'affiche. 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 lorsqu'une erreur ou une exception se produit, si vous avez implémenté des smart home notifications de suivi.
Un utilisateur émet une commande pour fermer la porte de son garage, mais celle-ci est bloquée 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 demandera à l'utilisateur "l'appareil est bloqué" après avoir reçu la notification. Vous pouvez envoyer les états d'appareil correspondants avec des 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 Erreurs et exceptions.