Suivi de la session

Enregistrez-vous pour recevoir des rappels d'événements de session en temps réel et surveiller l'activité de votre session depuis votre serveur d'application.

Grâce à la plateforme OpenTok, les développeurs peuvent surveiller certaines activités des clients utilisant les SDK client OpenTok, depuis leur serveur d'applications. En vous inscrivant aux callbacks via l'API REST OpenTok, votre URL de callback recevra des requêtes HTTP POST lorsqu'une session est créée ou supprimée, lorsqu'un client se connecte ou se déconnecte, et lorsqu'un client publie ou retire un flux d'une session de votre projet OpenTok. De plus, vous pouvez enregistrer un callback pour surveiller les événements liés aux archives OpenTok de votre projet.

Enregistrement des rappels

Les informations relatives aux événements de session et aux mises à jour de l'état des archives peuvent toutes être transmises à des points de terminaison HTTP au sein de votre serveur. Chaque fois qu'une activité enregistrée se produit, une requête HTTP est envoyée depuis l'infrastructure OpenTok vers votre point de terminaison.

Pour enregistrer un rappel :

  1. Visitez votre Page de compte de l'API Video de Vonage.

  2. Sélectionnez le projet OpenTok pour lequel vous souhaitez enregistrer un callback.

  3. Définissez l'URL de rappel dans la section Suivi de session.

    Sécuriser les rappels : Vous pouvez sécuriser les demandes de rappel de webhook avec des rappels signés, à l'aide d'un secret de signature. Voir Rappels sécurisés.

L'URL de rappel d'archive et l'URL de rappel de diffusion sont définies séparément de l'URL de rappel pour les événements de session . Définissez l'URL de rappel d'archive dans la section « Archive » de votre Page de compte de l'API Video de Vonage.

Important : Le service de surveillance de session ne désactive plus le transfert d'événements en cas d'échecs de livraison excessifs (comme c'était le cas dans les versions précédentes), puisqu'un mécanisme de réessai et de compensation est utilisé. Vous ne recevrez plus de courrier électronique en cas d'interruption du rappel de surveillance de session, puisque le service n'est ni suspendu ni désactivé.

Contrôle du démarrage et de l'arrêt des sessions

Le moment où les clients commencent à utiliser une session et le moment où une session cesse d'être utilisée, sessionCreated et sessionDestroyed sont envoyés à votre point de rappel enregistré.

Session créée

Cet événement est envoyé lorsque le premier client se connecte à une session. Si tous les clients se déconnectent (voir Session détruite), les clients peuvent se reconnecter ultérieurement à la même session.

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL de rappel que vous avez fournie. Le Content-Type de la requête est application/json. Les données de la requête sont un objet JSON de la forme suivante :

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionCreated",
  "timestamp": 1470257688309,
  "createdAt": 1470257688309
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "sessionCreated"

  • timestamp - Horodatage de l'envoi de l'événement de rappel

  • createdAt - Date à laquelle le premier client s'est connecté à la session.

Session détruite

Cet événement est envoyé lorsqu'une session cesse d'être utilisée :

  • Une minute après que tous les participants se sont déconnectés de la session.

  • Lorsqu'une session Video API se termine, ce qui peut se produire après 8 heures.

  • Lorsqu'un serveur Video API s'arrête de manière inattendue.

Après l'envoi de cet événement, vous pouvez toujours réutiliser la session. Les clients peuvent se reconnecter à la session en utilisant le même identifiant de session Session créée sera envoyé. Cependant, il est préférable que les clients se reconnectent en utilisant un nouvel identifiant de session.

Par ailleurs, conformément aux bonnes pratiques, vous devriez demander à vos clients de se reconnecter à de nouvelles sessions (en utilisant un nouvel identifiant de session) dans les 8 heures suivant la Session créée événement de rappel.

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL de rappel que vous avez fournie. Le Content-Type de la requête est application/json. Les données de la requête sont un objet JSON de la forme suivante :

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionDestroyed",
  "timestamp": 1470258896953,
  "createdAt" : 1470258896953,
  "reason" : "clientDisconnected"
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "sessionDestroyed"

  • timestamp - Horodatage de l'envoi de l'événement de rappel

  • createdAt - Date à laquelle cette session a cessé d'être utilisée

  • reason - Il est réglé sur l'une des valeurs suivantes :

    • "clientDisconnected" - Tous les clients se sont déconnectés de la session.

    • "forceDisconnected" - Un modérateur a déconnecté les clients de la session. Ou la session s'est interrompue. Ou un serveur Video API s'est arrêté de manière inattendue.

    • "mediaIdle" - Tous les clients ont été déconnectés de la session parce qu'ils n'ont pas publié ou souscrit à des flux dans les 4 heures suivant la connexion.

    • "serverRotation" — Tous les clients ont été déconnectés de la session en raison d'une rotation des serveurs. Vous pouvez éviter que les clients ne soient déconnectés lors d'une rotation des serveurs en les configurant pour qu'ils utilisent la migration de session. Voir Rotation des serveurs et migration des sessions.

Événements de notification de la session

Les sessionNotification est envoyé lorsqu'une rotation d'un groupe de serveurs Video API pour l'une de vos sessions est prévue. Cet événement est envoyé 4 heures et 1 heure avant la rotation programmée.

Les sessionNotification est une requête HTTP POST envoyée à l'URL de rappel de suivi de session que vous avez fournie. Le Content-Type de la requête est application/json. Les données de la requête sont un objet JSON de la forme suivante :

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "timestamp": 1470282888309,
  "remainingTime": 3600,
  "createdAt": 1470257688309
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "sessionNotification"

  • reason - Pour un événement de rotation du serveur, cette valeur est fixée à "serverRotation". (Actuellement, il s'agit du seul type d'événement de notification de session).

  • remainingTime - Temps restant, en secondes, jusqu'à ce que les serveurs de la session fassent l'objet d'une rotation. Cette valeur est fixée à 14 400 secondes (4 heures) ou 3 600 secondes (1 heure).

  • timestamp - Horodatage de l'envoi de l'événement de rappel

  • createdAt - Date à laquelle le premier client s'est connecté à la session.

Voir Rotation des serveurs et migration des sessions pour plus d'informations sur les rotations de serveurs de l'API Video et sur la manière de maintenir la connexion des clients lors des rotations de serveurs.

Surveillance de l'activité de connexion

Une fois correctement enregistrée, l'infrastructure OpenTok peut envoyer des requêtes HTTP concernant toutes les connexions établies (et interrompues) pour toutes les sessions d'un même projet. Cette fonctionnalité est particulièrement utile pour suivre la disponibilité des utilisateurs sans nécessiter de connexions supplémentaires ni de rapports provenant directement du point de terminaison.

Lorsque les clients reçoivent connectionCreated et connectionDestroyed événements survenant lorsque d'autres clients se connectent à une session ou s'en déconnectent ; ces mêmes événements sont envoyés à votre point de terminaison de rappel enregistré.

Connexion créée

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL que vous indiquez. Le type de contenu (Content-Type) de la requête est « application/json ». Les données de la requête sont un objet JSON se présentant sous la forme suivante :

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionCreated",
    "timestamp": 1470257688309,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": "TOKENDATA"
    }
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "connectionCreated"

  • timestamp — Millisecondes écoulées depuis l'époque Unix

  • connection - Un objet définissant la connexion, contenant les propriétés suivantes :

    • id - L'identifiant de la connexion

    • data — Les données de connexion (voir Connexion données)

    • createdAt — La date et l'heure de création de cet objet

Connexion détruite

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL que vous indiquez. Le type de contenu (Content-Type) de la requête est « application/json ». Les données de la requête sont un objet JSON se présentant sous la forme suivante :

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": ""
    }
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • reason - Pour un connectionDestroyed événement, cette valeur est définie sur l'une des options suivantes :

    • "clientDisconnected" — Un client s'est déconnecté de la session (par exemple, en appelant la méthode `Session.disconnect()` d'OpenTok.js ou en fermant le navigateur ou l'application).

    • "forceDisconnected" — Un modérateur a déconnecté le client de la session (en appelant la fonction OpenTok.js Session.forceDisconnect() ).

    • "networkDisconnected" - La connexion réseau s'est interrompue brusquement (par exemple, le client a perdu sa connexion internet).

    • "mediaIdle" — Le client a été déconnecté d'une session car il n'a ni publié ni souscrit à des flux dans les 4 heures suivant sa connexion.

    • "serverRotation" — Le client a été déconnecté d'une session en raison d'une rotation des serveurs. Vous pouvez éviter que les clients ne soient déconnectés lors d'une rotation des serveurs en les configurant pour qu'ils utilisent la migration de session. Voir Rotation des serveurs et migration des sessions.

  • event - "connectionDestroyed"

  • timestamp — Millisecondes écoulées depuis l'époque Unix

  • connection - Un objet définissant la connexion, contenant les propriétés suivantes :

    • id - L'identifiant de la connexion

    • data — Les données de connexion (voir Connexion données)

    • createdAt — La date et l'heure de création de cet objet

Surveillance des cours d'eau

Les points de terminaison du serveur peuvent également s'enregistrer pour recevoir des requêtes HTTP déclenchées par l'activité des flux sur toutes les sessions d'un projet donné. Lorsque des flux sont créés ou supprimés, la requête contient les données relatives au flux et à la connexion correspondant au flux qui a déclenché l'événement.

Lorsque les clients reçoivent streamCreated et streamDestroyed événements survenant en réponse à la publication d'informations par d'autres clients dans une session ; ces mêmes événements sont envoyés vers votre point de terminaison de rappel enregistré.

Flux créé

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL que vous indiquez. Le type de contenu (Content-Type) de la requête est « application/json ». Les données de la requête sont un objet JSON se présentant sous la forme suivante :

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamCreated",
    "timestamp": 1470258860571,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "streamCreated"

  • timestamp — Millisecondes écoulées depuis l'époque Unix

  • stream - Un objet qui définit le flux :

    • id - L'identifiant du flux

    • connection — La connexion associée à ce flux. Cet objet comprend les propriétés suivantes :

      • id - L'identifiant de la connexion

      • data — Les données de connexion (voir Connexion données)

      • createdAt — L'horodatage correspondant à la création de la connexion

    • createdAt — La valeur de l'horodatage correspondant à la création du flux

    • name — Le nom, s'il y en avait un, a été transmis lors de l'initialisation de l'éditeur associé à ce flux

    • videoType - Le type de vidéo envoyé sur ce flux, soit "camera", "screen", ou "custom" (ou indéfini pour un flux audio uniquement).

Stream détruit

Pour chaque événement distinct, le serveur envoie une requête HTTP POST à l'URL que vous indiquez. Le type de contenu (Content-Type) de la requête est « application/json ». Les données de la requête sont un objet JSON se présentant sous la forme suivante :

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

  • sessionId - L'identifiant de session associé à cet événement

  • projectId - L'identifiant du projet associé à cet événement

  • event - "streamDestroyed"

  • reason - Pour un streamDestroyed événement, cette valeur est définie sur l'une des options suivantes :

    • "clientDisconnected" — Le client s'est déconnecté de la session (par exemple, en appelant la méthode OpenTok.js Session.disconnect() ).

    • "forceDisconnected" — Un modérateur a déconnecté l'éditeur du flux de la session, en appelant OpenTok.js Session.forceDisconnect() méthode.

    • "forceUnpublished" — Un modérateur a contraint l'éditeur du flux à cesser de diffuser ce dernier, en faisant appel à OpenTok.js Session.forceUnpublish() méthode.

    • "mediaStopped" — L'utilisateur qui diffuse le flux a cessé de partager son écran. Cette valeur n'est utilisée que dans les flux vidéo de partage d'écran.

    • "networkDisconnected" La connexion réseau a été interrompue brusquement (par exemple, le client a perdu sa connexion Internet).

    • "serverRotation" — Le flux s'est interrompu car le client de publication a été déconnecté d'une session en raison de Rotation des serveurs de la Video API.

  • timestamp — Millisecondes écoulées depuis l'époque Unix

  • stream - Un objet qui définit le flux :

    • id - L'identifiant du flux

    • connection — La connexion associée à ce flux. Cet objet comprend les propriétés suivantes :

      • id - L'identifiant de la connexion

      • data — Les données de connexion (voir Connexion données)

      • createdAt — L'horodatage correspondant à la création de la connexion

    • createdAt — La valeur de l'horodatage correspondant à la création du flux

    • name — Le nom, s'il y en avait un, a été transmis lors de l'initialisation de l'éditeur associé à ce flux

    • videoType - Le type de vidéo envoyé sur ce flux, soit "camera", "screen", ou "custom" (ou indéfini pour un flux audio uniquement).

Suivi des archives

Chaque archive passe par plusieurs états tout au long de son cycle de vie. À chaque mise à jour de statut, un point de terminaison serveur disposant d’un enregistrement de statut d’archive recevra une requête HTTP. Cela s’avère particulièrement utile pour déclencher le post-traitement d’une archive ou pour effectuer toute tâche administrative nécessaire une fois qu’une archive a été transférée vers un stockage persistant. Pour plus d’informations, consultez la Statut des archives modifications section consacrée à l'archivage d'OpenTok du guide du développeur.

Surveillance des émissions

Voir le Suivi des changements d'état de la diffusion en direct section du guide du développeur consacré aux diffusions en direct OpenTok.

Suivi de la progression des appels SIP

Vous pouvez suivre les mises à jour d'état des connexions SIP vers une session OpenTok. Consultez la Suivi de la progression de l'appel section du guide du développeur « OpenTok SIP Interconnect ».

Suivi de l'expérience Composer

Vous pouvez suivre les mises à jour du statut des compositeurs d'expérience. Voir les Configuration des rappels du guide du développeur Experience Composer.

Suivi des sous-titres en direct

Vous pouvez surveiller les mises à jour d'état pour les sous-titres en direct. Voir la page Rappels de légendes en direct du guide du développeur de sous-titres en direct.