Skip to main content

Analytics

Crumbcast counts what's watched in its player, on watch pages and in embeds: how often, for how long, by whom, and how well it played. A player of your own, on your pages or in your apps, can report the same (Players of your own). A viewer token reads all of it, for a project, a video or a live broadcast.

A project's analytics

What's counted​

  • Views are plays: each time the player starts a video.
  • Viewings are a play and the watching that follows it, including watching it again within half an hour.
  • Watch time is the seconds actually played, not how long the page was open.
  • Days are UTC days.

A project's​

curl "https://your-crumbcast/api/v1/projects/$PROJECT_ID/analytics/?days=30" \
-H "Authorization: Bearer $CRUMBCAST_TOKEN"

days is the period, today included: 30 unless you say, up to 365. The answer has:

Field
views, previous_viewsPlays in the period, and in the period as long before it
watch, embed, custom, appOf those, on the watch page, in embeds, in players of your own on web pages, and in apps
all_timePlays ever
viewings, watch_seconds, average_view_secondsViewings, the seconds watched, and seconds per viewing
average_viewedHow much of a video a viewing watched, on average (0 to 1)
per_dayEach day's views and watch_seconds, oldest first
videosThe videos with the most plays
domainsThe sites with the most plays: embedding the player, or playing in one of their own
appsThe apps with the most plays, by their bundle or application ID

A video's​

Get Video Analytics answers the same for one video, with its retention in place of the top videos: 100 numbers, the share of viewings that watched each 1% of it, from the start to the end. Where it drops is where viewers stop.

import os

import requests

API = "https://your-crumbcast/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CRUMBCAST_TOKEN']}"}

stats = requests.get(f"{API}/videos/{video_id}/analytics/", params={"days": 90}, headers=headers)
stats.raise_for_status()
retention = stats.json()["retention"]

# The first point at which fewer than half the viewings were still watching
half = next((percent for percent, share in enumerate(retention) if share < 0.5), None)
print(f"Half the viewers are gone by {half}% of the video" if half is not None else "Most watch to the end")

Audience and quality​

Get Project Audience and Get Video Audience say who watched and how it played for them:

  • countries (ISO 3166-1 codes), devices (desktop, mobile, tablet, tv), browsers and systems: each with its viewings and watch time, most first.
  • referrers: the sites viewings came from, by host name (news.example.com): the page that linked to the watch page, or the one the player is embedded in. An empty name is a viewing opened directly, or from a page that sent no referrer.
  • startup_median_ms, startup_p90_ms: how long from pressing play to the first frame.
  • rebuffering: the share of the time playing that was spent waiting for the stream.
  • renditions: the share of watch time at each height, tallest first.

They're read from each viewing's events, which are kept for 90 days, so their days goes up to 90; views and watch time are kept by day, for periods up to 365.

Players of your own​

A video played in hls.js, Shaka Player, Video.js, AVPlayer, ExoPlayer or any other player (Play videos) is counted once the player reports it, as Crumbcast's own player does: it starts a viewing at the first play, then sends a beat every 15 seconds while playing with what it played. Its plays, watch time, retention, audience and quality then show in the analytics with everyone else's, under their own source.

Report from the viewer's device, never from your server. Crumbcast tells viewers apart, and finds their country and device, by the request itself: beats sent from a server would all be one viewer in one place. No API token is needed or wanted; a signed or password video takes the same ?token= as its playlist.

On a web page​

crumbcast/analytics, in the JavaScript SDK, reports any HTML video element, whatever plays into it:

import Hls from "hls.js";
import { track } from "crumbcast/analytics";

const video = document.querySelector("video");
const hls = new Hls();
hls.loadSource(`https://your-crumbcast/api/v1/videos/${videoId}/master.m3u8`);
hls.attachMedia(video);

const stop = track(video, { baseUrl: "https://your-crumbcast", video: videoId });
// Playing another video in the same element: stop(), then track it

track takes the video's token too, for a signed video, and domain and referrer if the page's own host name and document.referrer aren't what you want counted. Its views count as custom, by the page's site.

In an app, or anything else​

Send the two requests yourself, as JSON:

  1. At the first play, Start Viewing: POST /api/v1/videos/<id>/viewings/ with {"source": "app", "app": "com.example.tv"} (your bundle or application ID), or {"source": "custom", "domain": "example.com"} for a web page. It answers {"viewing": "<id>"}, or {"viewing": null} for a viewer it doesn't count (a bot): then send nothing more.

  2. Every 15 seconds while playing, and when it pauses, seeks, ends or goes to the background, Report a Beat: POST /api/v1/viewings/<viewing>/beats/ with

    • seq: 1 for the first beat, then one more each time;
    • ranges: the parts of the video played since the beat before, in seconds: [[12.0, 27.0]]. A seek ends one range and starts the next;
    • optionally startup_ms (once: from pressing play to the first frame), stalled_seconds (waiting for the stream since the beat before) and heights (the seconds played at each rendition, by its short side: {"1080": 15}).

    A 404 means the viewing is over (paused for more than half an hour): start another at the next play.

Crumbcast keeps the ranges to the video's length and to what the time since the last beat allows, so a player can't report more than was watched. Give your app a user agent of its own that names the device, as MyApp/2.3 (iPhone; iOS 18.1): a library's default, such as OkHttp's, is taken for a bot.

Live broadcasts​

List Broadcasts gives a live stream's latest broadcasts, and Get Broadcast Analytics one of them:

  • watching: the most watching at once, each minute it was on.
  • simulcast: its viewers on YouTube and Twitch, for targets made from a connected channel (Live streaming).
  • audience: who watched and how it played, as above, without referrers.

While a broadcast is on, Get Live Stream's broadcast has how many are watching now.

A broadcast's recording is a video of its own: its views from then on are that video's.