Analytics-API: Live-Messwerte

In diesem Thema werden die für Live-Streams verfügbaren Analysemetriken erläutert.

Einleitung

Die Wiedergabemetriken für Live-Streams, die vom Brightcove Live-Dienst bereitgestellt werden, sind in Echtzeit über die Analytics-API verfügbar. Diese Daten werden für erfasst Live-Streams nur; Die VoD-Wiedergabe ist nicht enthalten.

Die API stellt Livestream-Metriken über 2 Endpunkte bereit:

  • /v1/timeseries
  • /v1/events

Beide fragen denselben Datensatz ab, aggregieren die Ergebnisse jedoch unterschiedlich. In diesem Dokument werden deren Verwendung und Syntax beschrieben.

Messwerte

Dies sind die Metriken, die über die Live-Endpunkte verfügbar sind. Abfragen können mehrere Metriken anfordern.

Metrisch Beschreibung
alive_ss_ad_start Serverseitige Anzeigenimpressionen
ccu Einzelne Sitzungen; Anzahl der einzelnen Sitzungen (Fingerabdruck + Sitzung)
fingerprint_count Einzigartige Geräte; Anzahl verschiedener Fingerabdrücke (siehe unten)
video_impression Wie oft das Video in den Player geladen wurde
video_seconds_viewed Von allen Zuschauern angesehene Sekunden insgesamt
video_view Stream startet (nicht eindeutig)

Zum einzigartig Tracking weisen wir a Fingerabdruck zu jedem Gerät durch Kombinieren von (Remote IP + User-Agent + Player). Beachten Sie, dass wir keine tatsächliche Hardware-ID des Geräts selbst verwenden - dies verringert die Genauigkeit, hält uns jedoch datenschutzkonform.

Maße

Die folgenden Kombinationen werden unterstützt als dimensions und where Filterschlüssel:

  • video
  • video, country
  • video, device_type

Abfrageparameter

Beide Live-Endpunkte haben einige gemeinsame Parameter, die den Umfang und die Gruppierung der Abfrage steuern.

Parameter Syntax Erforderlich Standardwert Beschreibung
Abmessungen <dim1>,<dim2>,... Y - Abfragedimensionen (GROUP BY)
Metriken <metric1>,<metric2>,... Y - Ein oder mehrere Messwerte zum Melden
wo <dim1>==<value1>;... Y - Ein oder mehrere Abfragefilter; muss mindestens 1 Video enthalten
von <epoch> N 32 Tage ab jetzt Zeitraum beginnen
zu <epoch> N jetzt Ende des Zeitraums

Zeitfolgen

Die /v1/timeseries endpoint gibt eine Liste von Punkten entlang einer Zeitachse mit dem Wert der angeforderten Metrik zu jedem Zeitpunkt zurück. Punkte sind 1 Minute Buckets standardmäßig, können aber über einen Parameter geändert werden.

In diesem Zusammenhang geben Unique Metrics (ccu, fingerprint_count) den Maximalwert zu einem beliebigen Zeitpunkt in jedem Bucket an. Also eine Abfrage mit bucket_duration=1d gibt die maximale Parallelität für jeden Tag zurück, während eine Abfrage mit bucket_limit=1 gibt die maximale Parallelität an jedem Punkt im Stream zurück.

URI

/v1/timeseries/accounts/{account_id}

Zusätzliche Parameter

Parameter Syntax Erforderlich Standardwert Beschreibung
Dauer des Buckets <n>m (Protokoll)
<n>h (Std)
<n>d (Tage)
N 1m Dauer, die durch jeden Punkt repräsentiert wird. 1d ist 24 Stunden, kein Kalendertag.
eimer_limit <n> N - Anzahl der zurückzugebenden Punkte. Verwenden Sie entweder bucket_duration oder bucket_limit, aber nicht beide zusammen.

Antwort

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

Ereignisse

Die /v1/events endpoint gibt Metriksummen für den gesamten oder einen Teil eines Live-Videostreams zurück.

In diesem Zusammenhang stellen Unique Metrics (ccu, fingerprint_count) den Gesamtwert über den Abfragebereich dar. So zum Beispiel eine Abfrage ohne from/.to Parameter geben die Gesamtzahl von zurück einzigartig Sitzungen (ccu) und / oder Geräte (fingerprint_count) für den gesamten Stream.

URI

/v1/events/accounts/{account_id}

Zusätzliche Parameter

keiner

Antwort

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

Exportieren

Der Events-Endpunkt bietet auch einen herunterladbaren Bericht:

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

Die Antwort ist ein XLSX Datei mit Live-Messwerten auf 4 Blättern:

  • Zusammenfassung
  • Gleichzeitige Benutzer
  • Ansichten nach Gerätetyp
  • Ansichten nach Geografie

Anwendungsbeispiele

Für all diese Beispiele verwenden wir Account 1234, Video 5555 und gehen von einer aktuellen Uhrzeit von 12:00:00 Uhr UTC am 15. Februar 2020 aus.


Holen Sie sich die aktuelle Zuschauerzahl (CCU) für einen Livestream oder Kanal

Stellen Sie von bis vor mindestens 2 Minuten (11:58 Uhr) ein und verwenden Sie den letzten Punkt in der Antwort.

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


Erhalten Sie CCU-Grafikpunkte für einen Live-Stream der letzten 24 Stunden

Vergrößern (1-Minuten-Punkte)

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

Herauszoomen (1-Stunden-Punkte)

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


Holen Sie sich die maximale CCU pro Tag für einen Live-Kanal der letzten 7 Tage

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


Holen Sie sich während eines Live-Streams jederzeit die maximale CPU-Leistung

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


Erhalten Sie die Gesamtzahl der eindeutigen Zuschauer und der angezeigten Sekunden für mehrere Live-Streams

Video 5555 ist abgeschlossen; Zahlen sind endgültig. Video 5556 ist noch aktiv; Zahlen sind laufende Summen.

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


Erhalten Sie die Zuschauerzahlen und die Gesamtzahl der Anzeigen für ein einstündiges Programm auf einem Live-Kanal<

Das Programm wurde von 10:00 Uhr bis 11:00 Uhr (UTC) ausgestrahlt

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


Erhalten Sie Zuschauerzahlen nach Land für die Dauer eines Livestreams

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