Authentification silencieuse - Meilleures pratiques

Contourner le WiFi et forcer la connexion aux données mobiles avec les SDK

L'authentification silencieuse nécessite une connexion active aux données mobiles. Si la demande est faite par Wi-Fi, elle aboutira à une erreur. Pour garantir la réussite de la demande même lorsque l'utilisateur est en WiFi, Vonage fournit des services natifs d'authentification silencieuse. iOS et Android Les SDK qui imposent une connexion aux données mobiles.

L'utilisation des SDK permet également de minimiser l'impact sur l'interface utilisateur dans les cas particuliers :

Contrôles de connectivité (par exemple sdk_no_data_connectivity) afin de déclencher un basculement plus rapide et transparent.
Gestion des délais entre les redirections pour réduire l'attente dans des conditions de données mobiles lentes.
Prise en charge d'iOS 26 sur les marchés concernés (par exemple l'Espagne).

En outre, les SDK de Vonage gèrent les redirections HTTP (jusqu'à 10) et les délais d'attente (5 secondes, réinitialisation après chaque redirection).

Utiliser des points finaux régionaux pour réduire les temps de latence

Pour améliorer la latence de l'authentification silencieuse, nous recommandons d'utiliser le point d'extrémité régional de Vonage qui correspond à l'emplacement de votre utilisateur final :

Amérique du Nord : api-us.vonage.com
L'Europe : api-eu.vonage.com
Asie : api-ap.vonage.com

En utilisant des points de terminaison régionaux, vous vous assurez que les demandes sont acheminées le long du chemin le plus court possible, ce qui permet de minimiser les retards causés par les redirections.

Remarque : L'utilisation d'un point d'extrémité non régional (mondial) permet d'acheminer le trafic américain via les États-Unis. Cependant, tout le reste du trafic, y compris celui provenant de l'Asie-Pacifique (AP), sera acheminé via l'Europe, ce qui peut entraîner une augmentation de la latence.

Front-end

L'authentification silencieuse au sein de Verify présente un moyen simple et direct d'authentifier un utilisateur, offrant une expérience utilisateur améliorée par rapport à d'autres canaux.

Pour les cas d'utilisation liés à la création d'un nouveau compte, l'application mobile ne connaîtra pas le numéro de téléphone de l'utilisateur final, qui devra donc être collecté via un champ de saisie sur l'écran d'accueil. Par ailleurs, le numéro de téléphone d'un utilisateur final qui possède déjà un Account et qui tente de se connecter sans mot de passe est déjà enregistré. Dans ce cas, l'utilisateur final pourrait se voir présenter des champs de texte préremplis et la seule action nécessaire est de sélectionner "Verify".

Lors de l'expérience d'authentification silencieuse, assurez-vous que l'utilisateur est familiarisé avec le processus et qu'il est conscient que le processus d'authentification s'exécute en arrière-plan.

État en cours

Pour définir les attentes pendant que l'authentification s'exécute en arrière-plan, il est recommandé de.. :

Présentez une roue tournante ou un mécanisme de retour d'information similaire pour que l'utilisateur final sache que l'application mobile travaille sur la tâche d'authentification.
Il est également possible d'afficher un écran dédié avec le même indicateur de chargement et un texte supplémentaire.

Parcours de réussite

Si l'authentification silencieuse se termine avec succès, l'utilisateur doit être amené à un état de réussite clair sans avoir besoin d'entrer un code.

Chemin de repli

En cas d'échec pendant le flux d'authentification silencieuse, le front-end de l'application doit être ajusté afin que l'utilisateur puisse insérer le code pin pour terminer le processus 2FA. Ce code sera délivré via les canaux de basculement.

En résumé, la figure ci-dessous illustre les deux parcours de l'utilisateur : la voie de la réussite (l'authentification silencieuse s'effectue en arrière-plan) et l'option chemin de repli (l'utilisateur est invité à saisir un code de basculement).

Gestion des erreurs et des délais d'attente dans l'authentification silencieuse

En raison de sa nature, l'authentification silencieuse peut être affectée par des conditions externes telles qu'un manque de connectivité des données mobiles ou des interruptions temporaires du réseau. Pour garantir une expérience utilisateur fluide, votre application mobile doit s'appuyer sur la fonction d'authentification silencieuse. Bibliothèque du clientplutôt que d'implémenter ses propres contrôles réseau et sa propre gestion des délais.

Lorsque le SDK rencontre un problème, il lance des exceptions spécifiques qui indiquent ce qui n'a pas fonctionné. Par exemple, sdk_no_data_connectivityL'application est lancée lorsqu'il n'y a pas de connexion de données mobiles.

Éviter de lancer l'authentification silencieuse sans données mobiles

Avant de lancer une requête d'authentification silencieuse, utilisez la commande Bibliothèques des clients pour effectuer explicitement une vérification préalable de la connectivité cellulaire. Si le SDK détecte que les données mobiles ne sont pas disponibles (par exemple, si l'appareil est connecté uniquement au Wi-Fi ou s'il n'y a pas de signal), il renvoie false (iOS) ou CellularStatus.Unavailable (Android). Votre application doit vérifier ce résultat et basculer vers le canal de secours. Cela permet d'éviter des tentatives de requête inutiles et de réduire la durée globale de la vérification. Pour plus de détails sur la mise en œuvre, consultez la Fichier README de la bibliothèque client iOS ou Fichier README de la bibliothèque client Android.

Si la vérification préalable échoue, le canal d'authentification silencieuse doit être ignoré. Votre backend peut tout de même appeler POST /v2/verify, mais vous devrez le faire sans utiliser le canal d'authentification silencieuse, en vous limitant aux canaux de secours que vous aurez choisis (par exemple, SMS, RCS ou voix). Dans ce cas, aucun check_url est renvoyée et next_workflow n'est pas nécessaire, car le canal de secours est lancé directement.

Note: Si des problèmes de connectivité surviennent après la création de la requête « Verify » (par exemple, une interruption du réseau lors du chargement check_url), le SDK peut générer des exceptions telles que sdk_no_data_connectivity. Dans ce cas, utilisez la valeur renvoyée request_id et appeler next_workflow immédiatement via votre interface d'administration. Voir Comportement du délai d'attente pour plus de détails.

Comportement du délai d'attente

Votre application doit attraper ces exceptions et notifier à votre backend d'appeler la fonction next_workflow immédiatement. Cela permet de garantir que le flux de vérification se poursuit avec élégance, même lorsque le flux de travail de l'authentification silencieuse échoue ou ne peut pas se poursuivre.

Si l'application mobile n'entreprend aucune action pour passer au flux de travail suivant, le système interrompt automatiquement le processus au bout de 60 secondes et passe au flux de travail suivant.

Le diagramme de séquence ci-dessous illustre deux scénarios de défaillance : (1) la vérification préalable du SDK détecte que les données mobiles ne sont pas disponibles — l'authentification silencieuse est ignorée (donc pas de check_url est renvoyée), et (2) une requête « Verify » est créée avec succès, mais l'application mobile ne parvient pas à mener à bien le processus de redirection lors du chargement check_url (par exemple en raison de problèmes de réseau) :

Débit recommandé

Avant de lancer l'authentification silencieuse, appelez explicitement la méthode de vérification préalable du SDK afin de vérifier la connectivité mobile. Pour plus de détails sur la mise en œuvre, consultez le Fichier README de la bibliothèque client iOS ou Fichier README de la bibliothèque client Android.
Si la vérification préalable renvoie false (iOS) ou CellularStatus.Unavailable (Android), ignorez le canal d'authentification silencieuse. Votre backend peut toujours appeler POST /v2/verify, mais il faudrait le faire sans le canal d'authentification silencieuse — en utilisant uniquement les canaux de secours que vous avez choisis (par exemple, les SMS, le RCS ou la voix). Dans ce cas, aucun check_url est renvoyée et next_workflow n'est pas nécessaire, car le canal de secours est lancé directement.
Si la vérification préalable est réussie, lancez l'authentification silencieuse et envoyez la requête check_url via votre backend (POST /v2/verify).
Attendez que l'authentification silencieuse s'effectue en arrière-plan. Une fois l'opération réussie, passez à l'état « authentifié ».
Si une exception se produit après la création d'une requête « Verify » (par exemple lors du chargement check_url), interceptez-le et appelez votre backend pour déclencher next_workflow (nécessite request_id).
Si aucune réponse ou rappel n'est reçu dans le délai interne de votre application (par exemple, avant les 60 secondes par défaut), appelez next_workflow également.

Cette approche minimise le temps d'attente, améliore l'expérience de l'utilisateur et garantit que votre backend passe toujours à l'étape correcte du flux de travail.

`next_workflow` Comportement en cas de nouvelle tentative

Quand next_workflow Si cette méthode est appelée alors que la configuration de l'authentification silencieuse n'est pas encore terminée, Verify met l'événement en file d'attente et effectue une nouvelle tentative en interne pendant un court laps de temps.

Si le démarrage de l'authentification silencieuse prend un temps inhabituellement long et next_workflow si l'appel est effectué très tôt dans le flux, la fenêtre de réessai risque d'expirer. Dans ce cas, l'API renvoie une erreur HTTP 409 « Conflict » vous invitant à réessayer :

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

Scénarios de basculement

Dans cette section, nous énumérons tous les scénarios qui peuvent se produire lors d'une demande d'authentification silencieuse et nous conseillons des implémentations de basculement pour garantir une expérience optimale à l'utilisateur final.

Certains scénarios déclenchent un basculement immédiat vers le canal suivant, mais dans certains cas, le basculement n'est déclenché qu'après le délai d'attente par défaut de l'authentification silencieuse, qui est de 60 secondes. Le tableau ci-dessous résume les différents scénarios d'échec :

Scénario	Raison de l'échec	Code de défaillance	Réponse à l'échec	Basculement immédiat ?
1	Erreur d'authentification silencieuse	HTTP 409	`{ "title": "Silent Auth error", "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."}`	Oui
2	Erreur MSISDN	HTTP 409	`{ "title": "MSISDN Error", "detail": "Device MSISDN does not match."}`	Oui
3	Réseau non pris en charge	HTTP 412	`{ "title": "Network not supported", "detail": "Device number does not resolve to a supported Mobile Network Operator."}`	Oui
4	Erreur IP	HTTP 412	`{ "title": "IP Error", "detail": "IP Address does not resolve to a cellular device."}`	Oui
5	Erreurs du SDK iOS/Android	--	`sdk_no_data_connectivity`, `sdk_connection_error`, `sdk_redirect_error`, `sdk_error`	Non
6	`next_workflow` reçu trop tôt lors de la configuration de l'authentification silencieuse	HTTP 409	`{ "title": "Conflict", "detail": "The operation cannot be performed at this time. Please try again later."}`	Non

Facturation par authentification silencieuse

Lorsqu'une demande d'authentification silencieuse est initiée, elle génère une entrée pour les frais de la plate-forme Verify et une ou deux entrées supplémentaires représentant l'utilisation de l'authentification silencieuse. L'entrée marquée comme INITIATED n'est jamais facturé. Au total, une seule demande d'authentification silencieuse peut avoir jusqu'à trois enregistrements associés.

Essais

Pour tester l'authentification silencieuse Verify, vous pouvez procéder comme suit :

Utilisation Numbers virtuels.
Autoriser l'énumération des numéros des réseaux pris en charge par l'intermédiaire de l'application Registre du réseau.

Si un client a besoin d'envoyer du trafic en direct, il doit s'enregistrer auprès de l'opérateur de téléphonie mobile via le site Web de l'opérateur. Registre du réseau.