Tratar erros e exceções

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. Pense em possíveis cenários de falha e como seu dispositivo vai 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 "Acenda 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 vai solicitar ao usuário "o dispositivo não está disponível no momento" após receber a resposta. Não se esqueça 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 sem bloqueio para a intent EXECUTE

Um usuário tenta trancar a fechadura inteligente da porta da frente usando um dispositivo com Assistant. É possível controlar o bloqueio, mas você vai notar 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 solicitar ao usuário "o dispositivo tem bateria baixa" após receber a resposta.

Exemplo 3: notificações proativas de erros

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 vai mostrar ao usuário se a porta do dispositivo está aberta" depois de 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 avisará ao usuário que "o dispositivo está interrompido" depois de 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.