Verificação de usuário secundário

A verificação de usuários secundária permite adicionar segurança de dois fatores aos comandos de voz. Isso permite aumentar a segurança para determinadas ações, como desativar 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, que permite decidir quando usar um Google Assistant issue a challenge. For example, you can choose to issue a challenge for the OnOff trait for a security camera, but not issue a challenge for the OnOff trait for a light. You can also have Assistant issue challenges in certain situations for the same action. For example, you can request that Assistant issue a challenge request to open a door if an NFC keyfob is not in the proximity of that door, but not issue a challenge if the keyfob is present.

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 às intents QUERY e EXECUTE enviadas de Assistant de volta à ação e aceita uma resposta de erro challengeNeeded. Em seguida, Assistant envia a solicitação de intent para sua ação com os dados do desafio no bloco de desafio. Em seguida, valide 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 feitas na tela.

Tipos de dispositivos com suporte

A verificação secundária do usuário é compatível com todos os tipos de dispositivos.

Características do dispositivo com suporte

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 de usuário secundário compatíveis:

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

Nenhum desafio

Este exemplo mostra uma solicitação e uma resposta de 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
      }
    }]
  }
}

confirmação necessária

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

Estes são os tipos de desafio ackNeeded:

• ackÉ simples
• ackacked com estados de traço

ackNeeded simples

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.

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

confirmação necessária com estados de traço

Uma autenticação de confirmação do usuário secundária que pode usar estados para uma característica. Por exemplo, se você estiver trabalhando com a característica TemperatureSetting e a thermostatMode e a thermostatTemperatureSetpoint estiverem definidas, 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 realize uma ação específica com base em uma determinada solicitação.

As seguintes características e estados são compatíveis com ackNeeded. Uma listagem de uma característica específica indica que todos os estados são compatíveis.

• ArmDisarm (link em inglês)
• currentArmLevel
• currentStatusReport
• Preencher
• LockUnlock (em inglês)
• Ativado
• on
• OpenClose.
• Cena
• Temperatura da configuração
• thermostatMode
• thermostatTemperatureSetpoint
• thermostatTemperatureSetpointHigh
• thermostatTemperatureSetpointLow

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 aquecer e define a temperatura para 28 graus. Em seguida, o Assistant solicita aos usuários a confirmação para ligar o aquecimento e define a temperatura para 28 graus, já que um thermostatTemperatureSetpoint da 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
      }
    }]
  }
}

PIN necessário

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

Este exemplo mostra uma solicitação inicial e uma resposta com um desafio pinNeeded. O exemplo retorna uma resposta com um desafio pinNeeded, portanto, 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 a resposta com um desafio challengeFailedPinNeeded. Este desafio deve ser usado após uma falha inicial em um desafio pinNeeded.

Quando um tipo challengeFailedPinNeeded é retornado, Assistant pede o código de segurança novamente. Se o usuário executar muitas tentativas com falha, 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 a 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

Veja alguns códigos de erro que podem ser retornados com suas respostas:

• challengeFailedNotSetup: essa ação exige um código de segurança, mas não foi configurada no app do seu dispositivo.
• tooManyFailedAttempts - Há muitas tentativas com falha. Acesse o app do seu 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.