Quando dispositivos ou solicitações não funcionam como esperado, é importante oferecer um bom tratamento de erros e comunicação aos usuários para que eles entendam o que aconteceu e, sempre que possível, como corrigir o problema. Pense nos possíveis cenários de falha e como seu dispositivo responderá: e se um usuário interromper uma tarefa em andamento? E se um usuário solicitar uma ação de um dispositivo enquanto ele está off-line? Planejar esses problemas e ajudar o usuário a se recuperar deles pode evitar a frustração do usuário e criar uma experiência com mais qualidade para seus dispositivos.
Este guia fornece alguns exemplos de respostas de intent que lidam com erros. Consulte Erros e exceções para analisar os valores de errorCode
válidos para erros e exceções.
Exemplo 1: resposta de erro para a intent EXECUTE
Um usuário final tem duas luzes inteligentes instaladas na sala de estar. O usuário
emite um comando "acenda as luzes da sala de estar" e o Google enviou uma intent EXECUTE
ao URL de fulfillment. Você descobriu que os dispositivos do usuário estão off-line
e não controláveis. Portanto, o fulfillment retorna uma resposta EXECUTE
com
status
ERROR
e errorCode
deviceOffline
.
Este exemplo demonstra como retornar uma resposta EXECUTE
com uma
errorCode
de um dispositivo leve, conforme descrito anteriormente:
{ "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" } ] } }
O Google Assistant vai enviar uma mensagem pedindo ao usuário "o dispositivo não
está disponível no momento" depois de receber a resposta. Lembre-se de que você ainda
precisa enviar o estado off-line para dispositivos no estado do relatório depois de enviar
errorCode
deviceOffline
na resposta EXECUTE
.
Exemplo 2: exceção sem bloqueio para a intent EXECUTE
Um usuário tenta trancar a fechadura inteligente na porta da frente usando o dispositivo com
Assistant. É possível controlar o bloqueio, mas
você percebe que a bateria do dispositivo está baixa, então o fulfillment retorna uma resposta EXECUTE
com status
SUCCESS
e exceptionCode
lowBattery
.
Este exemplo demonstra como enviar uma resposta EXECUTE
com um
exceptionCode
de um dispositivo de bloqueio, conforme descrito anteriormente:
{ "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" } }] } }
O Assistant vai informar ao usuário "O dispositivo está com a bateria baixa" depois de receber a resposta.
Exemplo 3: notificações de erro proativas
Em alguns casos, pode ser útil alertar os usuários sobre um erro, especialmente para funções que os usuários esperam concluir automaticamente. Para características que oferecem suporte a notificações proativas, você pode notificar o usuário proativamente enquanto um erro acontece se você tiver implementado notificações proativas smart home.
Uma secadora inteligente está funcionando e alguém abre a porta antes de o ciclo terminar.
Você pode chamar o método reportStateAndNotifications
da API Google Home Graph para enviar uma notificação proativa com um errorCode
:
Este exemplo demonstra como enviar uma notificação proativa com uma
errorCode
em um dispositivo de secagem, conforme descrito anteriormente:
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 } } } } }
O Assistant vai informar ao usuário "a porta do dispositivo está aberta" depois de receber a notificação. É possível enviar os estados correspondentes do dispositivo junto com as notificações no mesmo payload.
Exemplo 4: notificação de acompanhamento
Para comandos de características que oferecem suporte a notificações de acompanhamento, é possível enviar uma notificação ao usuário enquanto ocorre um erro ou uma exceção, se você tiver implementado notificações de acompanhamento smart home.
Um usuário emite um comando para fechar o portão da garagem, mas a porta fica emperrada
durante o fechamento. É possível enviar uma notificação de acompanhamento com um 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 } } } } }
O Assistant vai perguntar ao usuário "o dispositivo está emperrado" depois de receber a notificação. É possível enviar os estados de dispositivo correspondentes com notificações no mesmo payload.
Para mais informações e detalhes sobre o errorCodes
, consulte a documentação de referência de Erros e exceções.