Verificación del usuario secundario

La verificación secundaria del usuario te permite agregar seguridad de dos factores a los comandos de 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 una característica específica del dispositivo, lo que te permite decidir cuándo hacer que Google Assistant emita un desafío. Por ejemplo, puedes elegir emitir un desafío para la característica OnOff de una cámara de seguridad, pero no emitir un desafío para la OnOff característica de una luz. También puedes hacer que Assistant emita desafíos 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 NFC no está cerca de esa puerta, pero no emitir un desafío si el llavero está presente.

El Assistant puede emitir dos tipos de desafíos: confirmación explícita 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 a tu acción y acepta una respuesta de error challengeNeeded. Assistant luego envía la solicitud de intent 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 dio 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 pantalla.

Cuándo usar la verificación secundaria del usuario

Puedes habilitar la verificación secundaria del usuario para cualquier tipo de dispositivo o característica. Sin embargo, debes implementar la verificación secundaria del usuario para ciertos tipos de dispositivos y características sensibles a la seguridad para obtener la certificación de tu integración.

Se requiere la verificación secundaria del usuario con el tipo de desafío pinNeeded para las siguientes combinaciones de características y tipos de dispositivos:

  • La característica OnOff si el tipo de dispositivo es CAMERA.
  • La característica OpenClose si el tipo de dispositivo es DOOR, GARAGE, GATE o WINDOW.
  • La característica LockUnlock cuando se desbloquea.
  • La característica ArmDisarm cuando se desarma o se cancela un desarme.
  • La característica Reboot, SoftwareUpdate o NetworkControl si el tipo de dispositivo es NETWORK o ROUTER.

Se requiere el tipo de desafío ackNeeded para la característica TemperatureSetting si el tipo de dispositivo es AC_UNIT y la integración se encuentra en Japón.

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 características como comentarios de respuesta. No se recomienda este tipo de desafío para dispositivos y características de seguridad.
  • pinNeeded: Es una verificación secundaria del usuario que requiere un número de identificación personal (PIN), que es ideal para dispositivos y características de seguridad.

Sin desafío

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

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

ackNeeded

Es una autenticación de confirmación secundaria del usuario que puede usar varios estados para una característica o una autenticación de confirmación simple.

Existen los siguientes tipos de desafíos ackNeeded:

ackNeeded simple

En este ejemplo, se muestra una solicitud y 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 características

Es una autenticación de confirmación secundaria del usuario que puede usar estados para una característica. Por ejemplo, si trabajas con la TemperatureSetting característica y se configuran thermostatMode y thermostatTemperatureSetpoint , Assistant puede preguntar ¿Confirmas que quieres establecer la calefacción 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.

Las siguientes características y estados admiten ackNeeded con estados de características. Una lista de una característica específica indica que se admiten todos sus estados.

  • ArmDisarm
    • Usa el tipo de desafío ackNeeded para armar o cancelar el armado del dispositivo, pero para las funciones de desarme y cancelación de desarme, se requiere el tipo de desafío pinNeeded.
  • Fill
  • LockUnlock
    • Usa el tipo de desafío ackNeeded para bloquear el dispositivo y el tipo de desafío pinNeeded para desbloquearlo.
  • OnOff
    • on
    • Usa el tipo de desafío ackNeeded para esta característica. Se requiere el tipo de desafío pinNeeded cuando se usa esta característica con dispositivos CAMERA.
  • OpenClose
    • Usa el tipo de desafío ackNeeded para esta característica. Se requiere el tipo de desafío pinNeeded cuando se usa esta característica con dispositivos DOOR, GARAGE, GATE o WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

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

Usuario Establece el modo del aire acondicionado en calefacción.
Google Assistant ¿Confirmas que quieres establecer 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 dispositivos de seguridad.

En este ejemplo, se muestra una solicitud y respuesta iniciales con un desafío pinNeeded. El ejemplo muestra una respuesta con un pinNeeded desafío, 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 Abre 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
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN incorrecto

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

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

Usuario 333222
Google Assistant Lo siento, 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"
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN válido

En este ejemplo, se muestra la solicitud y 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"
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "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
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "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 mostrar con tus respuestas:

  • tooManyFailedAttempts : Lo siento, hubo demasiados intentos fallidos. Ve a la app de tu dispositivo para completar esa acción.
  • pinIncorrect : Lo siento, el código de seguridad es incorrecto.
  • userCancelled : Aceptable

Consulta la lista completa de errores y excepciones.