Verificação de usuário secundário

A verificação secundária do usuário permite adicionar segurança de dois fatores aos comandos de voz. Isso permite adicionar mais segurança a 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 decidir quando Google Assistant emitir um desafio. Por exemplo, você pode escolher emitir um desafio para a característica OnOff de uma câmera de segurança, mas não emitir um desafio para a OnOff característica de uma luz. Também é possível fazer com que o Assistant emita desafios em determinadas situações para a mesma ação. Por exemplo, você pode solicitar que Assistant emita uma solicitação de desafio para abrir uma porta se um chaveiro NFC não estiver por perto, mas não emitir um desafio se o chaveiro estiver presente.

O 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 aos intents QUERY e EXECUTE enviados do Assistant de volta à sua ação e aceita uma resposta de erro challengeNeeded. Assistant Em seguida, envia a solicitação de intent de volta para sua ação com os dados do desafio no bloco de desafio. Em seguida, você pode validar os dados do desafio para determinar se o usuário deu a resposta de segurança correta.

Assistant usa a caixa de diálogo para emitir o desafio, mas, se você usar Assistant em superfícies que não são de voz, o PIN e as confirmações serão feitos na tela.

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

Você pode ativar a verificação secundária do usuário para qualquer tipo ou característica de dispositivo. No entanto, é necessário implementar a verificação secundária do usuário para determinados tipos e características de dispositivos sensíveis à segurança para que sua integração seja certificada.

A verificação secundária do usuário usando o tipo de desafio pinNeeded é necessária para as seguintes combinações de características e tipos de dispositivos:

• A característica OnOff se o tipo de dispositivo for CAMERA.
• A característica OpenClose se o tipo de dispositivo for DOOR, GARAGE, GATE ou WINDOW.
• A característica LockUnlock ao destrancar.
• A característica ArmDisarm ao desarmar ou cancelar um desarmamento.
• A característica Reboot, SoftwareUpdate ou NetworkControl se o tipo de dispositivo for NETWORK ou ROUTER.

O tipo de desafio ackNeeded é necessário para a característica TemperatureSetting se o tipo de dispositivo for AC_UNIT e a integração estiver no Japão.

Tipos de desafios aceitos

Estes são os tipos de desafios de verificação secundária do usuário aceitos:

• 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 exige 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 exige 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 resposta EXECUTE bem-sucedidas sem um desafio para acender as luzes.

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

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

Há os seguintes tipos de desafios ackNeeded:

• ackNeeded simples
• ackNeeded com estados de características

ackNeeded simples

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

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded com estados de características

Uma autenticação de confirmação secundária do usuário que pode usar estados para uma característica. Por exemplo, se você estiver trabalhando com a TemperatureSetting característica e thermostatMode e thermostatTemperatureSetpoint estiverem definidos, Assistant poderá perguntar Tem certeza de que quer definir o aquecimento no 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 estados a seguir oferecem suporte a ackNeeded com estados de características. Uma listagem de uma característica específica indica que todos os estados dela são aceitos.

• ArmDisarm
• Use o tipo de desafio ackNeeded para armar ou cancelar o armamento do dispositivo, mas, para as funções de desarmamento e cancelamento de desarmamento, o tipo de desafio pinNeeded é necessário.
• Fill
• LockUnlock
• Use o tipo de desafio ackNeeded para bloquear o dispositivo e o pinNeeded tipo de desafio para desbloquear.
• OnOff
• on
• Use o tipo de desafio ackNeeded para essa característica. O tipo de desafio pinNeeded é necessário quando essa característica é usada com dispositivos CAMERA.
• OpenClose
• Use o tipo de desafio ackNeeded para essa característica. O tipo de desafio pinNeeded é necessá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 resposta com um desafio ackNeeded que usa um estado de característica. Ele muda o modo do ar-condicionado para aquecimento e define a temperatura para 28 graus. Em seguida, Assistant pede aos usuários a confirmação para ligar o aquecimento e definir a temperatura para 28 graus, já que um thermostatTemperatureSetpoint de 28 é retornado como um estado na resposta.

{
  "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"
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "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 resposta inicial com um desafio pinNeeded. O exemplo retorna uma resposta com um desafio pinNeeded, então Assistant pede o PIN. Nesse momento, o usuário pode fornecer um PIN incorreto ou válido.

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

• PIN incorreto
• PIN válido

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "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 resposta com um desafio challengeFailedPinNeeded. Esse desafio precisa 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.

{
  "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"
          }
        }]
      }]
    }
  }]
}

{
  "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 resposta de um PIN válido.

{
  "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"
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}

{
  "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
          }
        }]
      }]
    }
  }]
}

{
  "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:

• tooManyFailedAttempts : muitas tentativas com falha. Acesse o app do dispositivo para concluir essa ação.
• pinIncorrect : o código de segurança está incorreto.
• userCancelled : OK

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