API d'analyse : Métriques en direct

Introduction

Métriques de lecture pour les diffusions en direct diffusées par le Brightcove en direct service sont disponibles en temps réel, via le API d'analyse. Ces données sont capturées uniquement pour les flux en direct ; la lecture VOD n'est pas incluse.

L'API fournit des métriques de diffusion en direct via 2 points de terminaison :

/v1/timeseries
/v1/events

Les deux interrogent le même ensemble de données, mais agrègent les résultats différemment. Ce document décrit l'utilisation et la syntaxe de chacun.

Métrique

Ce sont les métriques disponibles via les points de terminaison Live. Les requêtes peuvent demander plusieurs métriques.

Métrique	Description
`alive_ss_ad_start`	Impressions d'annonces côté serveur
`ccu`	Sessions uniques ; nombre de distincts (empreinte digitale + session)
`fingerprint_count`	Appareils uniques ; nombre d' empreintes digitalesdistinctes (voir ci-dessous)
`video_impression`	Nombre de fois où la vidéo a été chargée dans le lecteur
`video_seconds_viewed`	Nombre total de secondes regardées par tous les téléspectateurs
`video_view`	Le flux démarre (pas unique)

Pour unique suivi, nous attribuons un empreinte digitale à chaque appareil en combinant (Remote IP + User-Agent + Player). Notez que nous n'utilisons pas d'ID matériel réel de l'appareil lui-même - cela réduit la précision, mais nous maintient en conformité avec la confidentialité.

Dimensions

Les combinaisons suivantes sont prises en charge comme dimensions et where clés de filtrage:

video
video, country
video, device_type

Paramètres de requête

Les deux points de terminaison Live partagent certains paramètres communs qui contrôlent la portée et le regroupement de la requête.

Paramètre	Syntaxe	Obligatoire	Défaut	Description
dimensions	`<dim1>,<dim2>,...`	O	-	Dimensions de la requête (GROUP BY)
métrique	`<metric1>,<metric2>,...`	O	-	Une ou plusieurs métriques à signaler
où	`<dim1>==<value1>;...`	O	-	Un ou plusieurs filtres de requête ; doit inclure au moins 1 vidéo
de	`<epoch>`	N	dans 32 jours	Début de la plage horaire
à	`<epoch>`	N	maintenant	Fin de la plage horaire

Des séries chronologiques

Les /v1/timeseries endpoint renvoie une liste de points le long d'une chronologie, avec la valeur de la métrique demandée à chaque instant. Les points sont 1 minute buckets par défaut, mais peut être modifié via un paramètre.

Dans ce contexte, les métriques uniques (ccu , fingerprint_count ) indiquer le valeur maximum à tout moment pendant chaque seau. Donc une requête avec bucket_duration=1d renverra la simultanéité maximale pour chaque jour, tandis qu'une requête avec bucket_limit=1 renverra la simultanéité maximale à n'importe quel point du flux.

URI

/v1/timeseries/accounts/{account_id}

Paramètres supplémentaires

Paramètre	Syntaxe	Obligatoire	Défaut	Description
bucket_duration	`<n>m` ( minutes) `<n>h`(heures) `<n>d`(jours)	N	1m	Durée représentée par chaque point. `1d` est de 24 heures, pas un jour calendaire.
bucket_limit	`<n>`	N	-	Nombre de points à retourner. Utilisez soit `bucket_duration` ou `bucket_limit` , mais pas les deux ensemble.

Réponse

{
"<metric1>": {
"data": [
  {
    "dimensions": {
        "account": "<account>",
        "<dim1>": "<key1>",
        ...
        "<dimN>": "<keyN>"
      },
    "points": [
      {
        "timestamp": <bucket1>,
        "value": <value1>
      },
      ...,
      {
        "timestamp": <bucketN>,
        "value": <valueN>
      },
    ]
  }
]
},
"<metric2>": {
...
},
...
}

Evénements

Les /v1/events le point de terminaison renvoie les totaux des métriques pour tout ou partie d'un flux vidéo en direct.

Dans ce contexte, les métriques uniques (ccu , fingerprint_count ) représentent le Valeur totale sur la plage de requêtes. Par exemple, une requête sans from/to paramètres renverra le nombre total de unique sessions (ccu) et / ou périphériques (fingerprint_count) pour l'ensemble du flux.

URI

/v1/events/accounts/{account_id}

Paramètres supplémentaires

aucun

Réponse

{
"data": [
{
  "dimensions": {
    "account": "<account>",
    "<dim1>": "<key1>",
    ...
    "<dimN>": "<keyN>"
  },
  "totals": {
    "<metric1>": <value1>,
    ...
    "<metricN>": <valueN>
  }
}
]
}

Exportation

Le point de terminaison Events fournit également un rapport téléchargeable :

/v1/events/accounts/{account_id}/videos/{video_id}/export?format=xlsx

La réponse est un XLSX fichier avec des métriques en direct sur 4 feuilles :

Sommaire
Utilisateurs concurrents
Vues par type d'appareil
Vues par géographie

Exemples d'utilisation

Pour tous ces exemples, nous utiliserons Compte 1234 , Vidéo 5555 , et supposons une heure actuelle de 12h00 UTC au 15 février 2020.

Obtenez le nombre actuel de spectateurs (CCU) pour une diffusion en direct ou une chaîne

Définissez à partir d'au moins 2 minutes (11:58 AM), et utilisez le dernier point dans la réponse.

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581767880000

Obtenez des points de graphique CCU pour une diffusion en direct au cours des dernières 24 heures

Zoom avant (points d'une minute)

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1m

Zoom arrière (points d'une heure)

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1h

Obtenez le maximum de CCU par jour pour une chaîne en direct au cours des 7 derniers jours

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581206400000&bucket_duration=7d

Obtenez le maximum de CCU à tout moment pendant une diffusion en direct

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&bucket_limit=1

Obtenez le nombre total de spectateurs uniques et de secondes vues pour plusieurs diffusions en direct

La vidéo 5555 est terminée ; les chiffres sont définitifs. La vidéo 5556 est toujours active ; les chiffres sont des totaux cumulés.

/v1/events/accounts/1234?dimensions=video&metrics=fingerprint_count,video_seconds_viewed&where=video==5555,5556

Obtenez les totaux d'audience et d'annonces pour un programme d'une heure sur une chaîne en direct<

Programme diffusé de 10h00 à 11h00 (UTC)

/v1/events/accounts/1234?dimensions=video&metrics=alive_ss_ad_start,video_view,fingerprint_count&where=video==5555&from=1581760800000&to=1581764399999

Obtenez une audience par pays pendant toute la durée d'une diffusion en direct

/v1/events/accounts/1234?dimensions=video,country&metrics=video_view,fingerprint_count&where=video==5555