Observabilité côté client — iOS

Le SDK OpenTok pour iOS propose des appels permettant d'accéder aux statistiques en temps réel relatives au réseau et aux médias au cours d'une session vidéo. Ces appels fournissent des indicateurs détaillés sur la qualité du flux — tels que la perte de paquets, les données reçues et la bande passante — et peuvent être utilisés sur n'importe quel flux émetteur ou abonné.

Le SDK vidéo OpenTok fournit des indicateurs détaillés sur la qualité du flux via une API de statistiques de haut niveau — recommandée pour la plupart des cas d’utilisation — qui propose des statistiques audio, vidéo, réseau et côté émetteur sous une forme unifiée et adaptée à la session, qui reste stable lors des transitions entre connexions entre pairs. Pour un débogage avancé, le SDK offre également l'accès au rapport brut des statistiques WebRTC, qui reflète les données brutes relatives aux connexions entre pairs.

Le SDK expose également des mesures de l'état du réseau qui fournissent une évaluation de haut niveau de la santé de la connexion pour les éditeurs et les abonnés. Ces mesures comprennent un score d'état du réseau, la raison de ce score et, pour les abonnés, une source de dégradation indiquant quel côté de la connexion est responsable des problèmes observés. Voir État du réseau et dégradation pour plus de détails.

Ce guide comprend les sections suivantes :

API de statistiques sur les liens audio, vidéo et multimédia
Structures statistiques
Statistiques côté expéditeur
État du réseau et source de dégradation
Rapport statistique RTC
Exemple d'application

API de statistiques sur les liens audio, vidéo et multimédia

Le SDK OpenTok pour iOS envoie régulièrement des statistiques relatives à l'audio, à la vidéo et aux liens multimédias, tant pour les émetteurs que pour les abonnés. Ces statistiques comprennent le nombre de paquets, les débits binaires, les données relatives à la fréquence d'images, les indicateurs de pause/gel, les informations sur les codecs, ainsi que des indicateurs réseau au niveau du transport, tels que l'estimation de la bande passante et l'évaluation de l'état du réseau.

Les statistiques sont fournies par l'intermédiaire de :

OTPublisherKitNetworkStatsDelegate - statistiques côté éditeur (audio, vidéo)
OTSubscriberKitNetworkStatsDelegate - statistiques relatives aux abonnés (audio, vidéo)

Pour les recevoir, activez le délégué approprié sur l'éditeur ou l'abonné.

Activation des statistiques pour les éditeurs

Attachez une classe qui adopte OTPublisherKitNetworkStatsDelegate :

@interface MyViewController () <OTPublisherKitDelegate, OTPublisherKitNetworkStatsDelegate>
@end

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];
publisher.networkStatsDelegate = self;

Mettre en œuvre les rappels :

- (void)publisher:(OTPublisherKit *)publisher
videoNetworkStatsUpdated:(NSArray<OTPublisherKitVideoNetworkStats *> *)statsArray {

    OTPublisherKitVideoNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Video Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Video bytes sent: %lld", stats.videoBytesSent);
    NSLog(@"Video packets sent: %lld", stats.videoPacketsSent);
    NSLog(@"Video packets lost: %lld", stats.videoPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);

    for (OTPublisherKitVideoLayerStats *layer in stats.videoLayers) {
        NSLog(@"Layer: %dx%d", layer.width, layer.height);
        NSLog(@"  Encoded FPS: %f", layer.encodedFrameRate);
        NSLog(@"  Bitrate: %lld bps", layer.bitrate);
        NSLog(@"  Total bitrate (incl. RTP overhead): %lld bps", layer.totalBitrate);
        NSLog(@"  Codec: %@", layer.codec ?: @"unknown");
        NSLog(@"  Scalability mode: %@", layer.scalabilityMode ?: @"none");
        NSLog(@"  Quality limitation: %@", @(layer.qualityLimitationReason));
    }
}

- (void)publisher:(OTPublisherKit *)publisher
audioNetworkStatsUpdated:(NSArray<OTPublisherKitAudioNetworkStats *> *)statsArray {

    OTPublisherKitAudioNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Audio Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Audio bytes sent: %lld", stats.audioBytesSent);
    NSLog(@"Audio packets sent: %lld", stats.audioPacketsSent);
    NSLog(@"Audio packets lost: %lld", stats.audioPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);
}

- (void)publisher:(OTPublisherKit *)publisher
mediaLinkStatsUpdated:(NSArray<OTPublisherKitMediaLinkStats*>*)mediaLinkStats {
    
    if (mediaLinkStats.count == 0) return;
    OTPublisherKitMediaLinkStats *stats = mediaLinkStats.firstObject;
    
    NSLog(@"Publisher uplink bandwidth: %lld bps", stats.transport.connectionEstimatedBandwidth);
    NSLog(@"Network condition: %ld", (long)stats.transport.networkCondition);
    NSLog(@"Condition reason: %ld", (long)stats.transport.networkConditionReason);
}

Pour un éditeur dans une session acheminée (qui utilise l'option Routeur vidéo multimédia de Vonage, le tableau « stats » contient un objet définissant les statistiques relatives au flux multimédia audio ou vidéo unique envoyé au routeur multimédia Vonage Video. Dans une session relayée, le tableau « stats » contient un objet pour chaque abonné au flux publié.

Réception d'événements liés à la qualité vidéo chez les éditeurs

Si vous êtes également intéressé par les événements relatifs à la qualité de la vidéo, implémentez ce callback :

- (void)publisher:(OTPublisherKit *)publisher
videoQualityChanged:(OTPublisherKitVideoNetworkStats *)stats
           reason:(OTPublisherVideoEventReason)reason {

    NSLog(@"Publisher video quality event: %ld", (long)reason);
}

Réception d'événements liés à l'état du réseau sur les éditeurs

Pour recevoir les événements de modification des conditions du réseau pour l'éditeur, implémentez la fonction publisher:networkConditionChanged:mediaLinkStats:reason: rappel :

- (void)publisher:(OTPublisherKit *)publisher
networkConditionChanged:(OTPublisherKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Publisher network condition changed: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Reason: %ld", (long)mediaLinkStats.transport.networkConditionReason);
}

Ce rappel est déclenché lorsqu'un changement significatif de l'état du réseau est détecté pour l'éditeur. Elle inclut les statistiques de la liaison média en cours avec les métriques de transport. Voir État du réseau et source de dégradation pour plus de détails sur l'interprétation des notes et des raisons de l'état du réseau.

Activation des statistiques pour les abonnés

Joindre une classe qui adopte OTSubscriberKitNetworkStatsDelegate:

@interface MyViewController () <OTSubscriberKitDelegate, OTSubscriberKitNetworkStatsDelegate>
@end

OTSubscriber *subscriber = [[OTSubscriber alloc] initWithStream:stream
                                                       delegate:self];
subscriber.networkStatsDelegate = self;
[session subscribe:subscriber error:nil];

Mettre en œuvre les rappels :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats {
    NSLog(@"Video bytes received: %llu", stats.videoBytesReceived);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
audioNetworkStatsUpdated:(OTSubscriberKitAudioNetworkStats *)stats {
    NSLog(@"Audio packets received: %llu", stats.audioPacketsReceived);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
mediaLinkStatsUpdated:(OTSubscriberKitMediaLinkStats *)mediaLinkStats {
    
    NSLog(@"Local downlink bandwidth: %lld bps", mediaLinkStats.transport.connectionEstimatedBandwidth);
    NSLog(@"Remote publisher uplink bandwidth: %lld bps", mediaLinkStats.remotePublisherTransport.connectionEstimatedBandwidth);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

Réception d'événements liés à la qualité vidéo chez les abonnés

En outre, gérer les événements de modification de la qualité vidéo de l'abonné :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoQualityChanged:(OTSubscriberKitVideoNetworkStats *)stats
            reason:(OTSubscriberVideoEventReason)reason {

    NSLog(@"Subscriber video quality event: %ld", (long)reason);
}

Réception d'événements liés à l'état du réseau sur l'abonné

Pour recevoir les événements de changement d'état du réseau pour l'abonné, mettez en œuvre la fonction subscriber:networkConditionChanged:mediaLinkStats:reason: rappel :

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Local network condition: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Remote publisher network condition: %ld", (long)mediaLinkStats.remotePublisherTransport.networkCondition);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

Ce rappel est déclenché lorsqu'un changement significatif de l'état du réseau est détecté pour l'abonné ou l'éditeur distant. Il inclut les statistiques actuelles de la liaison média avec les métriques de transport locales et distantes et la source de dégradation. Voir État du réseau et source de dégradation pour plus de détails sur l'interprétation des notes et des raisons de l'état du réseau.

Structures de données statistiques

Cette section présente les structures et les propriétés fournies par l'API de statistiques audio et vidéo d'iOS. Bien que toutes les plateformes SDK vidéo exposent le même ensemble de statistiques, il peut y avoir des différences mineures dans la façon dont chaque plateforme structure ou nomme les champs individuels. Ces variations reflètent les conventions de conception des SDK spécifiques à chaque plateforme plutôt que des différences dans les mesures sous-jacentes.

Pour une explication indépendante de la plate-forme des statistiques disponibles et de ce qu'elles représentent, voir aperçu de l'observabilité du client.

`OTTransportStats`

Représente les mesures partagées au niveau du transport.

connectionEstimatedBandwidth - Estimation de la largeur de bande de connexion disponible (bps).
networkCondition - Score de l'état actuel du réseau (OTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGoodou OTNetworkConditionExcellent).
networkConditionReason - Raison principale de l'impact sur l'état du réseau (OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidth, OTNetworkReasonPacketLossou OTNetworkReasonNetworkConditionChange).

`OTPublisherKitVideoNetworkStats`

Fournit des statistiques sur la piste vidéo d'un éditeur. Elles comprennent :

connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
videoPacketsLost - Estimation des paquets vidéo perdus.
videoPacketsSent - Paquets vidéo envoyés.
videoBytesSent - Octets vidéo envoyés.
timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
videoLayers - Tableau de statistiques sur la couche vidéo (voir OTPublisherKitVideoLayerStats).

`OTPublisherKitAudioNetworkStats`

Fournit des statistiques sur la piste audio d'un éditeur. Elle comprend :

connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
audioPacketsLost - Estimation des paquets perdus.
audioPacketsSent - Paquets audio envoyés.
audioBytesSent - Octets audio envoyés.
timestamp - Horodatage Unix en millisecondes.
startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.

`OTPublisherKitVideoLayerStats`

Représente une couche simulcast ou une couche SVC.

width - Largeur de la trame encodée.
height - Hauteur du cadre codé.
encodedFrameRate - Images codées par seconde.
bitrate - Débit binaire de la couche (bps).
totalBitrate - Débit de la couche incluant le surdébit RTP (bps).
scalabilityMode - Descripteur SVC/scalability (par exemple, "L3T3").
qualityLimitationReason - Raison de la limitation de la qualité (bande passante, CPU, codec, résolution ou changement de couche).
codec - Le codec utilisé par cette couche vidéo.

`OTSenderStats`

Mesures d'estimation du côté de l'expéditeur (reflétées à la fois sur l'audio et la vidéo).

connectionMaxAllocatedBitrate - Débit maximum estimé pour la connexion de l'expéditeur.
connectionEstimatedBandwidth - Estimation de la largeur de bande actuelle (bps).

`OTSubscriberKitVideoNetworkStats`

Fournit des statistiques sur la piste vidéo d'un abonné. Elles comprennent :

videoPacketsLost - Estimation des paquets vidéo perdus.
videoPacketsReceived - Paquets vidéo reçus.
videoBytesReceived - Octets vidéo reçus.
timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
senderStats - Mesures du côté de l'expéditeur (facultatif).
width - Largeur de la trame décodée en pixels.
height - Hauteur de l'image décodée en pixels.
decodedFrameRate - Images décodées par seconde.
bitrate - Débit binaire vidéo (bps).
totalBitrate - Débit binaire incluant l'overhead RTP (bps).
pauseCount - Nombre de pauses (>5s depuis la dernière image). Inclut les désactivations intentionnelles et les cas de retour audio.
totalPausesDuration - Durée totale de la pause (ms).
freezeCount - Compte de gel (événement de gel défini par WebRTC).
totalFreezesDuration - Durée totale de l'arrêt sur image (ms).
codec - Codec du décodeur actuel.

`OTSubscriberKitAudioNetworkStats`

Fournit des statistiques sur la piste audio d'un abonné. Elles comprennent :

audioPacketsLost - Estimation des paquets perdus.
audioPacketsReceived - Paquets reçus.
audioBytesReceived - Octets reçus.
timestamp - Horodatage Unix en millisecondes.
senderStats - Mesures du côté de l'expéditeur (facultatif).

`OTPublisherKitMediaLinkStats`

Fournit des statistiques au niveau du transport pour la connexion d'un éditeur.

transport - Statistiques de transport pour cet éditeur (voir OTTransportStats)

`OTSubscriberKitMediaLinkStats`

Fournit des statistiques au niveau du transport pour les connexions d'un abonné, y compris une visibilité sur les performances du réseau de l'éditeur distant. Cela permet aux Applications de diagnostiquer si les problèmes de connexion proviennent de la liaison descendante de l'abonné ou de la liaison montante de l'éditeur.

transport - Statistiques de transport pour la connexion descendante de cet abonné (voir OTTransportStats)
remotePublisherTransport – Statistiques de transport relatives à la connexion montante de l'éditeur distant (voir OTTransportStats). Peut être limité si les statistiques côté expéditeur ne sont pas activées.
networkDegradationSource - Indique la source de la dégradation du réseau, le cas échéant (OTNetworkDegradationSourceNone, OTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemoteou OTNetworkDegradationSourceBothOrUnclear)

Statistiques côté expéditeur

Voir le aperçu des statistiques côté expéditeur.

Activation des statistiques côté expéditeur

Les statistiques côté émetteur sont reçues par les abonnés. Pour recevoir les statistiques côté émetteur, il faut les activer pour l'éditeur du flux en définissant l'attribut senderStatsTrack à la propriété true pour les OTPublisherKitSettings utilisé pour créer l'éditeur.

OTPublisherKitSettings *settings = [[OTPublisherKitSettings alloc] init];
settings.senderStatsTrack = YES;

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];

Si senderStatsTrack n'est pas activé, aucun canal de statistiques sur les expéditeurs ne sera publié pour cet éditeur. La valeur par défaut est NO.

Réception des statistiques côté expéditeur

Si l'éditeur a activé les statistiques côté expéditeur, les abonnés les reçoivent automatiquement par l'intermédiaire de l'option OTSubscriberKitNetworkStatsDelegate rappels décrite ci-dessus. Les senderStats sur les deux OTSubscriberKitVideoNetworkStats et OTSubscriberKitAudioNetworkStats fournit deux mesures :

connectionMaxAllocatedBitrate - Le débit maximum qui peut être estimé pour la connexion
connectionEstimatedBandwidth - La largeur de bande actuelle estimée pour la connexion

Ces mesures sont calculées par groupe audio-vidéo, de sorte que les mêmes valeurs apparaissent dans les statistiques vidéo et audio.

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats
{
    if (stats.senderStats) {
        OTSenderStats *sender = stats.senderStats;
        NSLog(@"Connection max allocated bitrate: %lld bps", (long long)sender.connectionMaxAllocatedBitrate);
        NSLog(@"Connection current estimated bandwidth: %lld bps", (long long)sender.connectionEstimatedBandwidth);
    }
}

État du réseau et source de dégradation

Le SDK fournit des mesures de l'état du réseau en temps réel pour les éditeurs et les abonnés, y compris une note d'état, la raison de cette note et une source de dégradation pour les abonnés. Pour une explication complète du modèle d'état du réseau, des scores, des raisons et de la manière de l'activer, voir le document aperçu de l'observabilité du client.

Les données sur l'état du réseau sont disponibles par le biais de deux canaux :

Statistiques périodiques : Les événements liés aux statistiques des médias comprennent des mesures de transport avec networkCondition et networkConditionReason. Pour les abonnés, les statistiques sur les liens avec les médias comprennent également remotePublisherTransport et networkDegradationSource.
Événements liés à la modification de l'état du réseau : Des rappels dédiés à l'éditeur et à l'abonné sont déclenchés lorsqu'un changement significatif de l'état du réseau est détecté.

L'exemple suivant montre comment utiliser les données sur l'état du réseau de l'abonné pour identifier la source de la dégradation :

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    OTNetworkCondition localCondition = mediaLinkStats.transport.networkCondition;
    OTNetworkCondition remoteCondition = mediaLinkStats.remotePublisherTransport.networkCondition;
    OTNetworkDegradationSource source = mediaLinkStats.networkDegradationSource;

    if (source == OTNetworkDegradationSourceLocal) {
        NSLog(@"Local network is degraded (condition: %ld)", (long)localCondition);
    } else if (source == OTNetworkDegradationSourceRemote) {
        NSLog(@"Remote publisher network is degraded (condition: %ld)", (long)remoteCondition);
    } else if (source == OTNetworkDegradationSourceBothOrUnclear) {
        NSLog(@"Degradation source unclear — local: %ld, remote: %ld", (long)localCondition, (long)remoteCondition);
    }
}

Rapport statistique RTC

Pour obtenir les statistiques de connexion entre pairs de bas niveau du serveur de publication, utilisez la commande OTPublisherKit getRtcStatsReport : méthode. Celle-ci fournit des rapports statistiques RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Définissez le OTPublisherKit rtcStatsReportDelegate propriété et mettre en œuvre la OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport: méthode avant d'appeler [OTPublisherKit getRtcStatsReport:]. Lorsque les statistiques sont disponibles, l'implémentation de la OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport: Le message est envoyé. Ce message contient un tableau de OTPublisherRtcStats objets, qui comportent une propriété jsonArrayOfReports. Il s'agit d'un tableau JSON contenant des rapports de statistiques RTC, dont le format est similaire à celui de l'objet RtcStatsReport implémenté dans les navigateurs Web (voir ces documents de Mozilla. Voir aussi cette documentation du W3C.

Pour obtenir les statistiques de connexion entre pairs de bas niveau des abonnés, utilisez la commande OTSubscriberKit getRtcStatsReport : méthode. Celle-ci fournit un rapport statistique RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Définissez le OTSubscriberKit rtcStatsReportDelegate propriété et mettre en œuvre la OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport: méthode avant d'appeler [OTSubscriberKit getRtcStatsReport:]. Lorsque les statistiques sont disponibles, l'implémentation de la OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport: Le message est envoyé. Ce message comprend un paramètre « jsonArrayOfReports ».

Exemple d'application

Les Exemple de statistiques côté expéditeur dans le SDK vidéo Vonage pour iOS (Swift) utilise les statistiques côté expéditeur dans une application mobile développée à l'aide du Client SDK iOS.