Verificação de usuário secundário

A verificação secundária do usuário permite adicionar segurança de segundo fator a comandos de voz. Isso permite adicionar segurança adicional para determinadas ações, como desligar uma câmera de segurança ou abrir uma porta. A verificação secundária do usuário não está vinculada a uma característica específica do dispositivo, o que permite que você decida quando fazer um desafio para o Google Assistant. Por exemplo, você pode optar por emitir um desafio para a característica OnOff para uma câmera de segurança, mas não para uma característica OnOff para uma luz. Também pode haver desafios de problemas Assistant em determinadas situações para a mesma ação. Por exemplo, é possível solicitar que Assistant emita uma solicitação de desafio para abrir uma porta se um chaveiro NFC não estiver próximo dela, mas não emitir um desafio se ele estiver presente.

A Assistant pode emitir dois tipos de desafios: confirmação explícita ou número de identificação pessoal (PIN). Isso adiciona um bloco de desafio às intents QUERY e EXECUTE enviadas de Assistant de volta à sua ação e aceita uma resposta de erro challengeNeeded. Em seguida, Assistant retorna a solicitação de intent para sua ação com os dados do desafio no bloco de desafio. Em seguida, é possível validar os dados do desafio para determinar se o usuário deu a resposta de segurança correta.

Assistant usa caixas de diálogo para emitir o desafio, mas se você usar Assistant em plataformas sem voz, o PIN e as confirmações serão feitos na tela.

Tipos de dispositivos com suporte

Todos os tipos de dispositivos oferecem suporte à verificação secundária do usuário.

Características do dispositivo compatível

A verificação secundária do usuário é compatível com todas as características do dispositivo.

Tipos de desafio compatíveis

Estes são os tipos de desafio de verificação secundária do usuário compatíveis:

  • Nenhum desafio: uma solicitação e uma resposta que não usam um desafio de verificação secundária do usuário.
  • ackNeeded: uma verificação secundária do usuário que requer confirmação explícita (sim ou não) e também pode usar estados de características como feedback de resposta. Esse tipo de desafio não é recomendado para dispositivos e características de segurança.
  • pinNeeded: uma verificação secundária do usuário que requer um número de identificação pessoal (PIN), ideal para dispositivos e características de segurança.

Nenhum desafio

Este exemplo mostra uma solicitação e uma resposta de EXECUTE bem-sucedidas sem o desafio de acender as luzes.

Usuário Acenda as luzes.
Google Assistant Ok, acendendo três luzes.
Solicitação
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Uma autenticação de confirmação de usuário secundária que pode usar vários estados para uma característica ou uma autenticação de confirmação simples.

Existem os seguintes tipos de desafio ackNeeded:

simples confirmado

Este exemplo mostra uma solicitação e uma resposta simples com um desafio ackNeeded para diminuir o brilho de uma luz e a confirmação para diminuir o brilho da luz.

Usuário Reduza a luz da luz da sala de estar.
Google Assistant Reduzindo o brilho da luz da sala de estar. Tem certeza?
Usuário Sim.
Google Assistant Reduzindo o brilho da luz da sala de estar.
Solicitação 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Resposta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Solicitação 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Resposta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

confirmado com estados de características

Uma autenticação de confirmação de usuário secundária que pode usar estados para uma característica. Por exemplo, se você estiver trabalhando com a característica TemperatureSetting e ambos thermostatMode e thermostatTemperatureSetpoint estiverem definidos, o Assistant poderá perguntar: Você quer mesmo definir o aquecimento do ar-condicionado para 28 graus?

Também é possível incluir um estado em uma resposta para que Assistant execute uma ação específica com base em uma determinada solicitação.

As características e os estados abaixo oferecem suporte a ackNeeded com estados de características. Uma listagem de uma característica específica indica que todos os estados dela têm suporte.

Este exemplo mostra uma solicitação e uma resposta com um desafio ackNeeded que usa um estado de característica. Ele muda o modo do ar-condicionado para aquecedor e define a temperatura para 28 graus. Em seguida, Assistant solicita aos usuários a confirmação para ativar o aquecimento e definir a temperatura em 28 graus, já que um thermostatTemperatureSetpoint de 28 é retornado como um estado na resposta.

Usuário Defina o modo ar-condicionado para aquecer.
Google Assistant Você quer mesmo definir o aquecimento do ar-condicionado para 28 graus?
Usuário Sim.
Google Assistantnt Definindo o aquecedor do ar-condicionado para 28 graus.
Solicitação 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}
Resposta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Solicitação 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Resposta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

O desafio pinNeeded é recomendado para dispositivos de segurança.

Este exemplo mostra uma solicitação e uma resposta iniciais com um desafio pinNeeded. O exemplo retorna uma resposta com um desafio pinNeeded, então Assistant solicita o PIN. Nesse ponto, o usuário pode fornecer um PIN incorreto ou válido.

Exemplo de solicitação e resposta para um PIN incorreto ou válido:

Usuário Destrancar a porta.
Google Assistant Você pode informar o código de segurança?
Solicitação
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN incorreto

Este exemplo mostra a solicitação e a resposta com um desafio challengeFailedPinNeeded. Este desafio precisa ser usado depois que um desafio pinNeeded inicial falhar.

Quando um tipo challengeFailedPinNeeded é retornado, o Assistant solicita o código de segurança novamente. Se o usuário realizar muitas tentativas com falha, você poderá retornar uma resposta de erro tooManyFailedAttempts. Veja mais informações em Respostas de erro.

Usuário 333222
Google Assistant O código de segurança está incorreto. Você pode informar o código de segurança?
Solicitação
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN válido

Este exemplo mostra a solicitação e a resposta de um PIN válido.

Usuário 333444
Google Assistant Destrancando a porta.
Solicitação
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Usuário Reduza a luz da luz da sala de estar.
Google Assistant Você pode informar o código de segurança?
Solicitação
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Respostas de erro

Estes são alguns códigos de erro que podem ser retornados com suas respostas:

  • challengeFailedNotSetup: esta ação exige um código de segurança, mas ele não foi configurado no app do dispositivo.
  • tooManyFailedAttempts - Muitas tentativas falharam. Acesse o app do dispositivo para concluir essa ação.
  • pinIncorrect - O código de segurança está incorreto.
  • userCancelled: OK.

Veja a lista completa de erros e exceções.