Verificação de usuário secundário

A verificação secundária do usuário permite adicionar segurança de segundo fator aos comandos de voz. Isso permite adicionar mais segurança 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 um atributo de dispositivo específico, o que permite que você decida quando o Google Assistant vai emitir um desafio. Por exemplo, é possível emitir um desafio para o atributo OnOff de uma câmera de segurança, mas não para o atributo OnOff de uma luz. O Assistant também pode emitir desafios em determinadas situações para a mesma ação. Por exemplo, é possível solicitar que o Assistant emita uma solicitação de desafio para abrir uma porta se um chaveiro NFC não estiver na proximidade dessa porta, mas não emita um desafio se o chaveiro estiver presente.

O Assistant pode emitir dois tipos de desafios: reconhecimento explícito 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, o Assistant envia a solicitação de intent de volta 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.

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

Quando usar a verificação secundária do usuário

É possível ativar a verificação secundária do usuário para qualquer tipo de dispositivo ou atributo. No entanto, é necessário implementar a verificação secundária do usuário para determinados tipos e atributos de dispositivos sensíveis à segurança para que sua integração seja certificada.

A verificação secundária do usuário com o tipo de desafio pinNeeded é necessária para as seguintes combinações de atributo e tipo de dispositivo:

  • O atributo OnOff se o tipo de dispositivo for CAMERA.
  • O atributo OpenClose se o tipo de dispositivo for DOOR, GARAGE, GATE ou WINDOW.
  • O atributo LockUnlock ao destrancar.
  • O atributo ArmDisarm ao desativar ou cancelar uma desativação.
  • O atributo Reboot, SoftwareUpdate ou NetworkControl se o tipo de dispositivo for NETWORK ou ROUTER.

O tipo de desafio ackNeeded é obrigatório para o atributo TemperatureSetting se o tipo de dispositivo for AC_UNIT e a integração estiver localizada no Japão.

Tipos de desafio compatíveis

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

  • Sem desafio: uma solicitação e 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 atributo como feedback de resposta. Esse tipo de desafio não é recomendado para dispositivos e atributos de segurança.
  • pinNeeded: uma verificação secundária do usuário que exige um número de identificação pessoal (PIN), ideal para dispositivos e atributos de segurança.

Nenhum desafio

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

Usuário Acender as luzes.
Google Assistant Ok, acendendo 3 luzes.
Solicitar
{
  "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 um atributo ou uma autenticação de confirmação simples.

Há os seguintes tipos de desafio do ackNeeded:

ackNeeded simples

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

Usuário Diminua a luz da sala de estar.
Google Assistant Diminuindo o brilho da luz da sala de estar. Tem certeza?
Usuário Sim.
Google Assistant Diminuindo 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"
    }]
  }
}

ackNeeded com estados de atributo

Uma autenticação de confirmação de usuário secundário que pode usar estados para um atributo. Por exemplo, se você estiver trabalhando com o atributo TemperatureSetting e as opções thermostatMode e thermostatTemperatureSetpoint estiverem definidas, 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 o Assistant execute uma ação específica com base em uma determinada solicitação.

Os seguintes atributos e estados são compatíveis com ackNeeded com estados de atributo. A listagem de um atributo específico indica que todos os estados dele são compatíveis.

  • ArmDisarm
    • Use o tipo de desafio ackNeeded para ativar ou cancelar a ativação do dispositivo, mas para as funções de desativação e cancelamento de desativação, o tipo de desafio pinNeeded é obrigatório.
  • Fill
  • LockUnlock
    • Use o tipo de desafio ackNeeded para bloquear o dispositivo e o tipo de desafio pinNeeded para desbloquear.
  • OnOff
    • on
    • Use o tipo de desafio ackNeeded para essa característica. O tipo de desafio pinNeeded é obrigatório quando esse atributo é usado com dispositivos CAMERA.
  • OpenClose
    • Use o tipo de desafio ackNeeded para essa característica. O tipo de desafio pinNeeded é obrigatório quando essa característica é usada com dispositivos DOOR, GARAGE, GATE ou WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

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

Usuário Defina o modo do ar-condicionado como aquecer.
Google Assistant Você quer mesmo definir o aquecimento do ar-condicionado para 28 graus?
Usuário Sim.
Google Assistant Definindo o aquecimento 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 pede 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 Destranque a porta.
Google Assistant Pode me informar seu código de segurança?
Solicitar
{
  "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. Esse desafio deve ser usado depois que um desafio pinNeeded inicial falhar.

Quando um tipo challengeFailedPinNeeded é retornado, Assistant pede o código de segurança novamente. Se o usuário fizer muitas tentativas com falha, você poderá retornar uma resposta de erro tooManyFailedAttempts. Consulte Respostas de erro.

Usuário 333222
Google Assistant O código de segurança está incorreto. Pode me informar seu código de segurança?
Solicitar
{
  "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.
Solicitar
{
  "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 Diminua a luz da sala de estar.
Google Assistant Pode me informar seu código de segurança?
Solicitar
{
  "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 do erro que podem ser retornados com as respostas:

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