Get viewer engagement

This guide provides information about registering and retrieving views from a video using the dashboard or the Livepeer API.

Register viewership metrics

To collect and register viewership metrics, you first need to configure your player. It is not required but we recommend that you use the Livepeer player to get viewership metrics, as it comes fully configured for the best playback experience with Livepeer. You can follow this guide to set it up.

We also support viewership data using custom players. Here's how to configure one to register viewership metrics as well:

Here's how to configure a custom player:

JavaScript

import { addMediaMetrics } from 'livepeer'

const source =
  'https://livepeercdn.com/recordings/bd600224-d93a-4ddc-a6ac-2d71e3c36768/index.m3u8'
const video = document.getElementById('my-video')

// setup your player before calling addMediaMetrics

addMediaMetrics(video, source, (e) => console.error('Error adding metrics', e))

React

import { addMediaMetrics } from 'livepeer'
import React, { useEffect, useRef, useState } from 'react'

export default function VideoPlayer() {
  const videoRef = useRef(null)
  const [source, setSource] = useState(
    'https://livepeercdn.com/recordings/bd600224-d93a-4ddc-a6ac-2d71e3c36768/index.m3u8'
  )

  useEffect(() => {
    if (videoRef.current) {
      // set up other stuff in your player before calling addMediaMetrics
      const metrics = addMediaMetrics(videoRef.current, source, (e) =>
        console.error('Error adding metrics', e)
      )
      return metrics?.destroy
    }
  }, [videoRef, source])

  return (
    <video
      controls
      ref={videoRef}
      src={source}
      style={{ width: '100%', maxWidth: '500px' }}
    />
  )
}

DashboardAPI

note

The viewership API is still in development. Currently, viewer count metrics are only available for on demand assets. The count registers start views with deduping logic that prevents users from attempting to inflate view counts. In the future, we'll support additional viewership and engagement metrics so you can better understand popularity and performance. Let us know if you have any particular feature requests related to metrics.

Step 1: Get the asset.id of an existing asset

Get the asset.id of an existing asset. An asset.id can be found in the response object of any API call working with assets. If you haven't created an asset yet, you can follow the upload a video asset guide to do so.

Step 2: Retrieve viewership data

Once you have the asset.id, you can make a request to get the viewership data.

JavaScript

const response = await fetch(
  "https://livepeer.studio/api/data/views/{assetId}/total",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
  }
);

const { startViews } = (await response.json())[0]

curl

curl --location --request GET https://livepeer.studio/api/data/views/{assetId}/total \
    -H "Authorization: Bearer $API_TOKEN"