Autenticación silenciosa: prácticas recomendadas

Omitir la conexión Wi-Fi y forzar la conexión de datos móviles con los SDK

La autenticación silenciosa requiere una conexión de datos móviles activa. Si la solicitud se realiza a través de Wi-Fi, se producirá un error. Para garantizar que la solicitud se realice correctamente incluso cuando el usuario esté conectado a una red Wi-Fi, Vonage ofrece una solución nativa iOS y Android SDKs que imponen una conexión de datos móviles.

El uso de los SDK también ayuda a minimizar el impacto en la experiencia del usuario en casos extremos:

Comprobaciones de conectividad (por ejemplo sdk_no_data_connectivity) para que pueda activar una conmutación por error más rápida y sin interrupciones.
Gestión del tiempo de espera entre redireccionamientos para reducir la espera en condiciones de datos móviles lentos.
Compatibilidad con iOS 26 en los mercados aplicables (por ejemplo, España).

Además, los SDK de Vonage gestionan las redirecciones HTTP (hasta 10) y controlan los tiempos de espera (5 segundos, que se reinician tras cada redirección).

Utiliza puntos de conexión regionales para reducir la latencia

Para mejorar la latencia de la autenticación silenciosa, recomendamos usar el punto final regional de Vonage que coincida con la ubicación de tu usuario final:

América del Norte: api-us.vonage.com
Europa: api-eu.vonage.com
Asia: api-ap.vonage.com

Al utilizar puntos de conexión regionales, te aseguras de que las solicitudes se enruten por la ruta más corta posible, lo que ayuda a minimizar los retrasos provocados por las redirecciones.

Nota: Si se utiliza un punto de conexión no regional (global), el tráfico procedente de EE. UU. se enrutará a través de EE. UU. Sin embargo, el resto del tráfico, incluido el procedente de Asia-Pacífico (AP), se enrutará a través de Europa, lo que podría provocar un aumento de la latencia.

Front-end

La autenticación silenciosa dentro de Verify presenta una forma fácil y directa de autenticar a un usuario, proporcionando una experiencia de usuario mejorada en comparación con otros canales.

En los casos de creación de nuevas cuentas, la aplicación móvil no conocerá el número de teléfono del usuario final, por lo que dicho número deberá introducirse a través de un campo de entrada en la pantalla de bienvenida. Por otra parte, en el caso de un usuario final que ya disponga de una cuenta y esté intentando iniciar sesión sin contraseña, su número de teléfono ya estará almacenado. En este caso, se le podrían mostrar campos de texto ya rellenados y la única acción necesaria sería seleccionar «Verify».

Durante la experiencia de autenticación silenciosa, asegúrate de que el usuario esté familiarizado con el proceso y sea consciente de que la autenticación se está llevando a cabo en segundo plano.

Estado «En curso»

Para establecer expectativas mientras la autenticación se ejecuta en segundo plano, se recomienda:

Muestra un indicador giratorio o un mecanismo de retroalimentación similar para que el usuario final sepa que la aplicación móvil está realizando la tarea de autenticación.
Alternativamente, muestre una pantalla dedicada con el mismo indicador de carga y texto adicional.

Camino del éxito

Si la autenticación silenciosa se completa correctamente, el usuario debe ser llevado a un estado de éxito claro sin necesidad de introducir un código.

Ruta de retorno

En caso de que se produzca un fallo durante el proceso de autenticación silenciosa, es necesario adaptar la interfaz de la aplicación para que el usuario pueda introducir el código PIN y completar el proceso de autenticación de dos factores (2FA). Este código se enviará a través de los canales de conmutación por error.

En resumen, la siguiente figura ilustra ambos recorridos de usuario: el camino hacia el éxito (la autenticación silenciosa se completa en segundo plano) y el botón ruta alternativa (se pide al usuario que introduzca un código de conmutación por error).

Gestión de errores y tiempos de espera en la autenticación silenciosa

Debido a su naturaleza, la autenticación silenciosa puede verse afectada por condiciones externas como la falta de conectividad de datos móviles o interrupciones temporales de la red. Para garantizar una experiencia de usuario fluida, su aplicación móvil debe confiar en la Biblioteca de clientesel sistema de gestión de excepciones integrado, en lugar de implementar sus propias comprobaciones de red y gestión de tiempos de espera.

Cuando el SDK encuentra un problema, lanza excepciones específicas que indican qué ha ido mal. Por ejemplo, sdk_no_data_connectivityse lanza cuando no hay conexión de datos móviles disponible.

Evite iniciar la autenticación silenciosa sin datos móviles

Para disfrutar de la mejor experiencia de usuario, te recomendamos que compruebes la conexión de datos móviles. antes de Iniciar una solicitud de autenticación silenciosa.

Si el dispositivo no tiene una conexión de datos móviles activa, no inicie el paso de Autenticación silenciosa y pase directamente al siguiente canal de verificación (SMS, RCS, voz, etc.). Esto evita intentos de solicitud innecesarios y reduce el tiempo total de verificación.

Nota: En Biblioteca de clientes actualmente valida la conectividad durante la ejecución. Lanza excepciones (como sdk_no_data_connectivity) cuando se detectan problemas después de que se haya iniciado la solicitud. Véase Comportamiento en caso de tiempo de espera para saber cómo gestionar estas excepciones en tiempo de ejecución.

Comportamiento en caso de tiempo de espera

Tu aplicación debería capturar estas excepciones y notificar a tu servidor para que llame a la next_workflow inmediatamente. Esto garantiza que el flujo de verificación continúe correctamente incluso cuando el flujo de trabajo de autenticación silenciosa falle o no pueda continuar.

Si la aplicación móvil no realiza ninguna acción para pasar al siguiente flujo de trabajo, el sistema se desconectará automáticamente transcurridos 60 segundos y pasará al siguiente flujo de trabajo.

El siguiente diagrama de secuencia ilustra una situación en la que la aplicación móvil no recibe correctamente las redirecciones, posiblemente debido a problemas de red durante la solicitud de check_url:

Caudal recomendado

Inicia la solicitud de autenticación silenciosa mediante el SDK.
Si el SDK lanza una excepción (por ejemplo, sdk_no_data_connectivity), captúralo y llama inmediatamente al backend next_workflow punto final.
Si no se recibe ninguna respuesta ni llamada de retorno dentro del tiempo de espera interno de tu aplicación (por ejemplo, antes de los 60 segundos predeterminados), llama a next_workflow también.
En caso contrario, espera a la llamada de retorno de autenticación normal.

Este enfoque minimiza el tiempo de espera, mejora la experiencia del usuario y garantiza que su backend avance siempre al paso correcto del flujo de trabajo.

`next_workflow` Comportamiento de reintento

En next_workflow Si se invoca esta función mientras la autenticación silenciosa aún está completando su configuración, Verify pone el evento en cola y vuelve a intentarlo internamente durante un breve intervalo de tiempo.

Si la autenticación silenciosa tarda más de lo habitual en iniciarse y next_workflow Si se invoca muy al principio del flujo, es posible que caduque el plazo de reintento. En ese caso, la API devuelve un error HTTP 409 (Conflicto) y te indica que lo intentes de nuevo:

{
  "type": "https://developer.vonage.com/en/api-errors/verify-v2#conflict",
  "title": "Conflict",
  "detail": "The operation cannot be performed at this time. Please try again later.",
  "instance": "my-trace-id-trigger-next-replication-delay"
}

Escenarios de conmutación por error

En esta sección enumeramos todos los escenarios que pueden producirse durante una solicitud de autenticación silenciosa y aconsejamos implementaciones de conmutación por error para garantizar la mejor experiencia del usuario final.

Algunos escenarios activan una conmutación por error inmediata al siguiente canal, sin embargo hay casos en los que la conmutación por error sólo se activa después del tiempo de espera predeterminado de Autenticación silenciosa de 60 segundos. Consulte la tabla siguiente, que resume los distintos escenarios de fallo:

Escenario	Motivo del fallo	Código de fallo	Respuesta ante fallos	¿Conmutación por error inmediata?
1	Error de autenticación silencioso	HTTP 409	`{ "title": "Silent Auth error", "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."}`	Sí
2	Error MSISDN	HTTP 409	`{ "title": "MSISDN Error", "detail": "Device MSISDN does not match."}`	Sí
3	Red no soportada	HTTP 412	`{ "title": "Network not supported", "detail": "Device number does not resolve to a supported Mobile Network Operator."}`	Sí
4	Error IP	HTTP 412	`{ "title": "IP Error", "detail": "IP Address does not resolve to a cellular device."}`	Sí
5	Errores del SDK de iOS/Android	--	`sdk_no_data_connectivity`, `sdk_connection_error`, `sdk_redirect_error`, `sdk_error`	No
6	`next_workflow` recibido demasiado pronto durante la configuración de la autenticación silenciosa	HTTP 409	`{ "title": "Conflict", "detail": "The operation cannot be performed at this time. Please try again later."}`	No

Facturación de autenticación silenciosa

Cuando se inicia una solicitud de Autenticación Silenciosa, se genera una entrada para la tarifa de la plataforma Verify y una o dos entradas adicionales que representan el uso de la Autenticación Silenciosa. La entrada marcada como INITIATED nunca se factura. En total, una sola solicitud de autenticación silenciosa puede tener hasta tres registros asociados.

Pruebas

Para probar la autenticación silenciosa de Verify, puedes hacer lo siguiente:

Uso números virtuales.
Permitir números de listado para las redes compatibles a través de la Registro de red.

Si un cliente necesita enviar tráfico en directo, debe registrarse en el operador de telefonía móvil a través de la aplicación Registro de red.