Quando dispositivos ou solicitações não funcionam como esperado, é importante oferecer um bom tratamento e comunicação de erros para que os usuários entendam o que aconteceu e, sempre que possível, como corrigir. Pense em possíveis cenários de falha e como seu dispositivo precisa responder: e se um usuário interromper uma tarefa em andamento? E se um usuário solicitar uma ação em um dispositivo enquanto ele estiver 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 de maior qualidade para seus dispositivos.
Este guia apresenta alguns exemplos de respostas de intent que processam erros. Consulte
Erros e exceções para
analisar os valores válidos de errorCode 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 "acender as luzes da sala de estar", e o Google envia uma intent EXECUTE
para o URL de fulfillment. Você descobriu que os dispositivos do usuário estão off-line
e não sã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 um
errorCode de um dispositivo de luz, 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 solicita ao usuário "o dispositivo não
está disponível no momento" após receber a resposta. Lembre-se de que você ainda
precisa enviar o estado off-line para dispositivos no estado de relatório depois de enviar
errorCode deviceOffline na resposta EXECUTE.
Exemplo 2: exceção não de bloqueio para a intent EXECUTE
Um usuário tenta trancar a fechadura inteligente da porta da frente usando
Assistant. Você pode controlar a fechadura, mas
a bateria do dispositivo está fraca. Portanto, a resposta de 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 solicita ao usuário "o dispositivo está com pouca bateria" após receber a resposta.
Exemplo 3: notificações de erro proativas
Em alguns casos, pode ser útil alertar os usuários sobre um erro, principalmente para funções que os usuários esperam que sejam concluídas automaticamente. Para recursos que ofereçam suporte a notificações proativas, você pode notificar o usuário proativamente enquanto um erro acontece se tiver implementado smart home notificações proativas.
Uma secadora inteligente está em uso e alguém abre a porta antes do ciclo terminar.
É possível 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 um
errorCode de 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 solicita ao usuário "a porta do dispositivo está aberta" após receber a notificação. É possível enviar os estados do dispositivo correspondentes com notificações no mesmo payload.
Exemplo 4: notificação de acompanhamento
Para comandos de atributos que oferecem suporte a notificações de acompanhamento, é possível enviar uma notificação de acompanhamento ao usuário enquanto um erro ou uma exceção acontece, se você tiver implementado smart home notificações de acompanhamento.
Um usuário emite um comando para fechar a porta da garagem, mas ela fica presa
enquanto fecha. Você pode 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 solicita ao usuário "o dispositivo está bloqueado" após receber a notificação. É possível enviar os estados do dispositivo correspondentes com notificações no mesmo payload.
Para mais informações e detalhes sobre errorCodes, consulte a documentação de referência
Errors and exceptions.