Lorsque les appareils ou les 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, dans la mesure du possible, comment le corriger. Assurez-vous de réfléchir aux scénarios de défaillance 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 alors qu'il est hors connexion ? En planifiant ces problèmes et en aidant vos utilisateurs à les résoudre, vous pouvez éviter leur frustration et leur offrir une expérience de meilleure qualité sur vos appareils.
Ce guide présente quelques exemples de réponses d'intent qui gèrent les erreurs. Consultez la section Erreurs et exceptions pour consulter 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 ampoules 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 avez constaté que les appareils de l'utilisateur étaient hors connexion et qu'ils ne pouvaient 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"
}
]
}
}
Après avoir reçu la réponse, Google Assistant indique à l'utilisateur que l'appareil n'est pas disponible pour le moment. N'oubliez pas que vous devez toujours envoyer l'état hors connexion pour les 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 la serrure connectée de sa porte d'entrée à l'aide de Assistant. Vous pouvez 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'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 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 d'une erreur, en particulier pour les fonctions que les utilisateurs s'attendent à voir s'exécuter automatiquement. Pour les traits compatibles avec les notifications proactives, vous pouvez envoyer une notification proactive à l'utilisateur en cas d'erreur si vous avez implémenté des smart home notifications proactives.
Un sèche-linge connecté fonctionne 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 des appareils correspondants avec les notifications dans la même charge utile.
Exemple 4: Notification de suivi
Pour les commandes de traits 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é des notifications de suivi smart home.
Un utilisateur envoie une commande pour fermer sa porte de garage, mais la porte 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 indique à l'utilisateur que l'appareil est bloqué après avoir reçu la notification. Vous pouvez envoyer les états des appareils 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 sur les erreurs et exceptions.