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 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.