Rétablissement après des interruptions de service grâce à la Video API Vonage

Introduction

Les applications vidéo en temps réel doivent fonctionner en permanence. Que vous organisiez une consultation de télésanté, une séance de conseil financier ou un événement virtuel de grande envergure, vos utilisateurs finaux ne tolèrent aucune interruption inexpliquée. Lorsqu'un problème survient au niveau de la plateforme, la différence entre une reprise sans heurts et un utilisateur frustré se résume souvent à une seule chose : la capacité de votre application à « écouter ».

Au cours des deux dernières années, la plateforme Video API de Vonage a intégré un ensemble important de fonctionnalités de résilience : rappels en cas d’interruption de service, migration automatique des sessions et infrastructure à autoréparation. La plupart de ces fonctionnalités ont été annoncées dans les notes de mise à jour du SDK et webinaires sur la feuille de route, mais elles n’avaient pas encore été regroupées en un seul endroit. C’est précisément l’objectif de cet article.

Si vous avez développé votre application avant 2023, il y a de fortes chances que vous ne tiriez pas parti des dernières fonctionnalités que nous avons mises à disposition. Dans cet article, nous passerons en revue ces fonctionnalités afin de nous assurer que vous exploitez pleinement tout ce que Vonage a à offrir. 

Comment la plateforme gère les perturbations

Avant d'aborder les fonctionnalités que votre application doit offrir, il est utile de comprendre ce que la plateforme fait automatiquement.

L' Video API Vonage fonctionne dans plus de 11 centres de données régionaux dotés d’une infrastructure redondante et soumis à des contrôles d’intégrité continus. Lorsqu’un serveur doit être remplacé ou tombe en panne de manière inattendue, le système de surveillance de la plateforme détecte le problème et déclenche la procédure de reprise. Dans la plupart des cas, la plateforme se rétablit automatiquement sans que vous ou vos utilisateurs n’ayez à intervenir.

Mais « la plupart » ne signifie pas « tous ». Dans les cas où une session, une diffusion, une archive ou un appel SIP est affecté, la plateforme envoie désormais un rappel à votre serveur d'applications, immédiatement, sans attendre la mise à jour de la page d'état. Il vous appartient d'intercepter ce rappel et d'agir en conséquence.

Étape 1 : Enregistrez vos URL de rappel

Les rappels en cas d'interruption de service ne sont envoyés que si vous avez configuré des URL de rappel dans votre projet. Sans celles-ci, aucun des événements décrits ci-dessous ne parviendra à votre serveur d'applications.

Tableau de bord vidéo Vonage

1. Connectez-vous à votre tableau de bord de l'API Vonage.

2. Aller à Applications et sélectionnez votre application prenant en charge la Video (ou créez-en une nouvelle).

3. Cliquez sur « Modifier », puis accédez à Fonctionnalités → Video.

4. Sous « Surveillance des sessions », saisissez votre URL de rappel pour les événements de session.

5. Configurer des URL de rappel distinctes pour l'archivage, la surveillance des appels SIPet Experience Composer selon les besoins.

6. Cliquez sur Enregistrer.

Environnement OpenTok (portail d'account TokBox)

1. Connectez-vous à votre Account Video API Vonage.

2. Sélectionnez le projet que vous souhaitez configurer.

3. Faites défiler jusqu’à Paramètres du projet.

4. Sous chaque service (Surveillance des sessions, Archivage, Surveillance des appels SIP), cliquez sur Configurer et saisissez votre URL de rappel.

Exécution des callbacks et tentatives de réessai : La plateforme utilise une politique de réessai avec délai d'attente exponentiel. Si votre serveur est temporairement indisponible, les callbacks sont réessayés à partir de 5 secondes, avec un doublement du délai jusqu'à un maximum de 15 minutes, pendant une durée maximale de 24 heures. Au bout de 24 heures, l'événement concerné est abandonné. Assurez-vous que votre point de terminaison de callback renvoie un 200 pour accuser réception.

Règles du pare-feu : Si votre serveur de rappel limite le trafic entrant par adresse IP, autorisez la plage d'adresses IP du service de rappel Vonage : 216.147.0.0/18.

Étape 2 : Gérer les rappels en cas d'interruption de service

Les rappels en cas d'interruption de service sont des webhooks standard POST envoyées à vos URL enregistrées. Elles utilisent des formats d'événements existants avec de nouveaux codes de motif indiquant une défaillance imprévue du côté de la plateforme — et non une déconnexion normale du client.

Voici ce à quoi vous pouvez vous attendre pour chaque prestation et ce qu'il faut faire lorsque vous en bénéficiez.

Séance Video

Lorsqu'un serveur multimédia de la Video API s'arrête de manière inattendue, vous recevrez une sessionDestroyed événement à l'URL de rappel de surveillance de votre session :

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "sessionDestroyed",
  "reason": "forceDisconnected",
  "timestamp": 1700000000000
}

Le signal clé ici est "reason": "forceDisconnected" - cela indique une déconnexion imposée par la plateforme, et non une déconnexion normale du client.

Mesure de rétablissement : Créer une nouvelle session et reconnectez vos terminaux. Ne réutilisez pas l'identifiant de session supprimé. Une session prend fin une minute après la déconnexion du dernier participant, et toute tentative de reconnexion à une session supprimée peut entraîner l'acheminement des connexions vers des serveurs qui ne sont plus en mesure de traiter le trafic. La création d'une session ne prend que quelques millisecondes ; il n'y a donc aucune raison pratique de mettre en cache et de réutiliser les identifiants de session d'un appel à l'autre.

Interconnexion SIP

En cas d'interruption imprévue du service SIP, vous recevrez une callDestroyed rappel à l'adresse URL de surveillance SIP :

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "callDestroyed",
  "reason_code": "703",
  "reason_message": "Unexpected Clearing",
  "timestamp": 1700000000000
}

reason_code: 703 indique une coupure inattendue du côté de la plateforme, par opposition à une coupure normale de la communication 700).

Mesure de rétablissement : Recomposez le numéro du terminal SIP à l'aide de l' API Dial pour rétablir l'appel SIP.

Radiodiffusion

Deux types de notifications en cas d'interruption de diffusion sont possibles ; elles sont toutes deux transmises à votre URL de surveillance de la diffusion :

Erreur d'URL RTMP/HLS (en started état) :

• Pour le protocole RTMP : vous recevrez "status": "error" pour chaque URL de point de terminaison RTMP concernée.

• Pour HLS : vous recevrez "hlsStatus": "error" sur le point de terminaison HLS.

Erreur interne du serveur :

{
  "status": "failed",
  "reason": "Internal server failure",
  "event": "broadcast"
}

Action de récupération : Renvoyer une nouvelle diffusion sur la même session à l'aide de l' API de diffusion, puis mettez à jour l'URL de diffusion pour tous les points de terminaison clients qui consommaient le flux.

Archives (Enregistrement)

{
  "id": "ARCHIVE_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure"
}

Action de récupération : Réémettre une nouvelle archive au cours de la même session à l'aide de l' API d'archivage. Notez que le contenu enregistré jusqu'au moment de la panne peut être partiellement disponible ; vérifiez l'état de l'archive après l'interruption.

Compositeur d'expérience

{
  "id": "RENDER_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure",
  "event": "render"
}

Action de récupération : Lancez un nouveau rendu Experience Composer sur la session à l’aide de l’ API de rendu.

Étape 3 : Activer la migration de session

Les rappels en cas d'interruption de service vous informent lorsqu'un problème survient afin que vous puissiez réagir. La migration de session va encore plus loin : elle maintient automatiquement la connexion de votre session en cours lorsque le serveur sous-jacent est remplacé, ce qui évite aux participants d'avoir à se reconnecter manuellement.

La migration de session est désormais disponible pour tous dans le Client SDK 2.31 (août 2025).

Ce qu'il couvre

La migration de session gère la couche des sessions actives :

• Sessions de vidéo en direct (tous les participants se reconnectent automatiquement)

• Appels SIP via l'API Dial

• Connexion audio via WebSockets à l'aide de l'API Connect

Important : La migration de session ne concerne que la session en direct. Les archives, les diffusions et les rendus d'Experience Composer en cours d'exécution au moment d'une rotation ne sont ne sont pas migrés automatiquement ; utilisez les callbacks de perturbation décrits ci-dessus pour gérer ces services.

Activation de la migration de session pour les SDK Web et natifs

Transmettre sessionMigration: true lors de l'initialisation de la session :

// JavaScript SDK

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

Cette option est également disponible dans les SDK pour iOS, Android, Windows, Linux et macOS — consultez le guide sur la rotation des serveurs pour connaître la syntaxe spécifique à chaque plateforme.

Activation de la migration de session pour SIP (API Dial)

Inclure sessionMigration: true dans le corps de la requête de l'API Dial :

{
  "sessionId": "YOUR_SESSION_ID",
  "token": "YOUR_TOKEN",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Activation de la migration de session pour Audio Connector (Connect API)

Le même sessionMigration: true indicateur s'applique également au corps de la requête de l'API Connect.

Remarque : sessionMigration la valeur par défaut est false et doit être explicitement activée. Nous recommandons de l'activer pour toutes les sessions de production, en particulier pour les sessions de longue durée ou celles dans les secteurs de la santé, de la finance ou d'autres contextes à haut risque où une reconnexion manuelle serait perturbante.

Meilleures pratiques

Gardez à l'esprit les points suivants :

Gérez les callbacks de manière idempotente. Dans certains cas exceptionnels, votre gestionnaire de callbacks peut recevoir plusieurs fois le même événement. Assurez-vous que votre logique de récupération (recommande SIP, redémarrage d'une archive, etc.) peut être appelée plusieurs fois en toute sécurité sans créer de ressources en double.

Répondez rapidement par un 200. La plateforme considère qu’un rappel a été transmis uniquement lorsqu’elle reçoit une 200 réponse HTTP. Si votre gestionnaire met trop de temps à répondre, la plateforme peut effectuer une nouvelle tentative. Accusez réception immédiatement et exécutez la logique de récupération de manière asynchrone si nécessaire.

Testez vos procédures de reprise avant la mise en production. Le Vonage Video Playground et Session Inspector sont des outils utiles pour observer les événements de session et vérifier que votre gestionnaire de rappel reçoit et traite correctement les événements.

Ne réutilisez pas les identifiants de session supprimés. Cela mérite d'être répété. Une session prend fin une minute après la déconnexion du dernier participant. Se reconnecter à un identifiant de session supprimé peut entraîner l'établissement de connexions vers des serveurs en cours d'arrêt. Créez toujours une nouvelle session.

Conclusion

La plateforme Video API de Vonage est conçue pour s'auto-réparer, mais votre application doit jouer un rôle actif dans ce processus. Voici un résumé :

Pour en savoir plus

• Guide sur la rotation des serveurs et la migration des sessions

• Guide de surveillance des sessions

• Référence de l'API REST Video

• Comment configurer les rappels de surveillance des sessions