Verificación del usuario secundario

La verificación secundaria del usuario te permite agregar seguridad de segundo factor a los comandos por voz. Esto te permite agregar seguridad adicional para ciertas acciones, como apagar una cámara de seguridad o abrir una puerta. La verificación secundaria del usuario no está vinculada a un rasgo específico del dispositivo, lo que te permite decidir cuándo Google Assistant debe emitir un desafío. Por ejemplo, puedes optar por emitir un desafío para el rasgo OnOff de una cámara de seguridad, pero no para el rasgo OnOff de una luz. También puedes tener problemas de Assistant en ciertas situaciones para la misma acción. Por ejemplo, puedes solicitar que Assistant emita una solicitud de desafío para abrir una puerta si un llavero con llave NFC no está cerca de esa puerta, pero no emitir un desafío si el llavero está presente.

La Assistant puede emitir dos tipos de desafíos: reconocimiento explícito o número de identificación personal (PIN). Esto agrega un bloque de desafío a los intents QUERY y EXECUTE que se envían desde Assistant de vuelta a tu acción y acepta una respuesta de error challengeNeeded. Luego, Assistant envía la solicitud de intención a tu acción con los datos del desafío en el bloque de desafío. Luego, puedes validar los datos del desafío para determinar si el usuario proporcionó la respuesta de seguridad correcta.

Assistant usa el diálogo para emitir el desafío, pero si usas Assistant en superficies que no son de voz, el PIN y las confirmaciones se realizan en la pantalla.

Tipos de dispositivos compatibles

La verificación secundaria del usuario es compatible con todos los tipos de dispositivos.

Traits de dispositivos compatibles

La verificación secundaria del usuario es compatible con todos los atributos del dispositivo.

Tipos de desafíos admitidos

Estos son los tipos de desafíos de verificación secundaria del usuario admitidos:

  • Sin desafío: Es una solicitud y respuesta que no usa un desafío de verificación secundaria del usuario.
  • ackNeeded: Es una verificación secundaria del usuario que requiere una confirmación explícita (sí o no) y también puede usar estados de rasgos como comentarios de respuesta. No se recomienda este tipo de desafío para dispositivos y rasgos de seguridad.
  • pinNeeded: Es una verificación secundaria del usuario que requiere un número de identificación personal (PIN), lo que resulta ideal para los dispositivos y las características de seguridad.

Sin impugnación

En este ejemplo, se muestra una solicitud y respuesta EXECUTE exitosas sin un desafío para encender las luces.

Usuario Enciende las luces.
Google Assistant De acuerdo. Se encenderán 3 luces.
Solicitud
{
  "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
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Es una autenticación secundaria de reconocimiento del usuario que puede usar varios estados para un rasgo o una autenticación de reconocimiento simple.

Existen los siguientes tipos de desafíos de ackNeeded:

ackNeeded simple

En este ejemplo, se muestra una solicitud y una respuesta simples con un desafío ackNeeded para atenuar una luz y la confirmación para atenuarla.

Usuario Atenúa la luz de la sala de estar.
Google Assistant Atenuando la luz de la sala de estar. ¿Confirmas la acción?
Usuario Sí.
Google Assistant Atenuando la luz de la sala de estar.
Solicitud 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
          }
        }]
      }]
    }
  }]
}
Respuesta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Solicitud 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
          }
        }]
      }]
    }
  }]
}
Respuesta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded con estados de rasgos

Es una autenticación secundaria de reconocimiento del usuario que puede usar estados para un rasgo. Por ejemplo, si trabajas con el rasgo TemperatureSetting y se establecen thermostatMode y thermostatTemperatureSetpoint, Assistant puede preguntar ¿Seguro que quieres establecer la temperatura del aire acondicionado en 28 grados?

También puedes incluir un estado en una respuesta para que Assistant realice una acción específica en función de una solicitud determinada.

Los siguientes rasgos y estados admiten ackNeeded con estados de rasgo. La lista de una característica específica indica que se admiten todos sus estados.

En este ejemplo, se muestra una solicitud y una respuesta con un desafío ackNeeded que usa un estado de rasgo. Cambia el modo del aire acondicionado a calefacción y establece la temperatura en 28 grados. Luego, Assistant les pide a los usuarios que confirmen que quieren encender la calefacción y establecer la temperatura en 28 grados, ya que se devuelve un thermostatTemperatureSetpoint de 28 como estado en la respuesta.

Usuario Establece el modo de aire acondicionado en calor.
Google Assistant ¿Confirmas que quieres configurar la calefacción del aire acondicionado en 28 grados?
Usuario Sí.
Google Assistant Se establecerá la calefacción del aire acondicionado en 28 grados.
Solicitud 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"
          }
        }]
      }]
    }
  }]
}
Respuesta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Solicitud 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
          }
        }]
      }]
    }
  }]
}
Respuesta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

Se recomienda el desafío pinNeeded para los dispositivos de seguridad.

En este ejemplo, se muestran una solicitud y una respuesta iniciales con un desafío pinNeeded. El ejemplo devuelve una respuesta con un desafío pinNeeded, por lo que Assistant solicita el PIN. En este punto, el usuario puede proporcionar un PIN incorrecto o válido.

Ejemplo de solicitud y respuesta para un PIN incorrecto o válido:

Usuario Destraba la puerta.
Google Assistant ¿Puedes decirme tu código de seguridad?
Solicitud
{
  "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
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN incorrecto

En este ejemplo, se muestran la solicitud y la respuesta con un desafío challengeFailedPinNeeded. Este desafío se debe usar después de que falle un desafío pinNeeded inicial.

Cuando se devuelve un tipo challengeFailedPinNeeded, Assistant vuelve a solicitar el código de seguridad. Si el usuario realiza demasiados intentos fallidos, puedes devolver una respuesta de error tooManyFailedAttempts. Consulta Respuestas de error.

Usuario 333222
Google Assistant Lo sentimos, el código de seguridad es incorrecto. ¿Puedes decirme tu código de seguridad?
Solicitud
{
  "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"
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN válido

En este ejemplo, se muestran la solicitud y la respuesta de un PIN válido.

Usuario 333444
Google Assistant Destrabando la puerta.
Solicitud
{
  "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"
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Usuario Atenúa la luz de la sala de estar.
Google Assistant ¿Puedes decirme tu código de seguridad?
Solicitud
{
  "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
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Respuestas de error

Estos son algunos códigos de error que se pueden devolver con tus respuestas:

  • tooManyFailedAttempts: Lo sentimos, se registraron demasiados intentos fallidos. Ve a la app del dispositivo para completar la acción.
  • pinIncorrect: Lo sentimos, el código de seguridad es incorrecto.
  • userCancelled: Aceptar

Consulta la lista completa de errores y excepciones.