React Video Analytics

Easily generate and post video player metrics

Table of contents

• React Video Analytics
  • Installation
  • Usage
    • Setup
    • Attach
    • Send
  • API
    • AnalyticsProvider
      • Props
      • Types
        • PlayerConfig<Player = unknown>
    • useAnalytics
      • Options
      • Types
        • ReportMetrics
        • ReportAction
        • BrowserState
        • ReportHeaders
        • ReportError
  • Authors
  • License

Installation

To install and set up the library, run:

$ npm install --save react-video-analytics

Or if you prefer using Yarn:

$ yarn add react-video-analytics

Usage

Setup

Begin by wrapping your app with the AnalyticsProvider.

import { AnalyticsProvider } from 'react-video-analytics'

...

return (
  <AnalyticsProvider>
    <App />
  </AnalyticsProvider>
)

Attach

Using the useAnalytics hook, attach a reference to your video player.

import { useAnalytics } from 'react-video-analytics'

const MyComponent = () => {
  const videoRef = useRef<HTMLVideoElement>(null)
  
  useAnalytics(videoRef)
  
  return (
    <video ref={videoRef} />
  )
}

Send

Implement the send option to send metrics to your analytics service. The send function will be called every time the video player emits a ReportAction which you can reference via metrics.action. The following example uses axios to post the metrics payload to an API endpoint:

import axios from 'axios'
import { useAnalytics } from 'react-video-analytics'

const MyComponent = () => {
  const videoRef = useRef<HTMLVideoElement>(null)
  
  useAnalytics(videoRef, {
    send: (metrics) => {
      // Send metrics to your analytics service
      axios.post('https://my-api.com/video-analytics', metrics)
    }
  })
  
  return (
    <video ref={videoRef} />
  )
}

API

AnalyticsProvider

Use the AnalyticsProvider to create custom video player configurations. By default, react-video-analytics supports a standard HTML video player. It also ships with an optional VimePlayerConfig that you can use instead if your project uses a Vime video player.

Props

Prop	Type	Default value	Description
defaultPlayerConfig (optional)	PlayerConfig	VideoPlayerConfig	Provides the default player configuration to use.
defaultTimeInterval (optional)	number	30000	The default interval, in milliseconds, to call send when the timeupdate event is emitted
viewerIdKey (optional)	string	'react-video-analytics-viewer-id'	The storage key name to use for storing the viewer's unique identifier.

Types

PlayerConfig<Player = unknown>

Prop	Type	Description
getVideoElement	<P extends Player>(player: P) => Promise<HTMLVideoElement>	Defines how to retreive the html video element from a generic video player component

Examples

Using a custom player component:

import { PlayerConfig } from 'react-video-analytics'

...

return (
  <AnayticsProvider
    defaultPlayerConfig={{ 
      getVideoElement: (player: SomeCustomPlayer) => {
        // Write logic to return the html video element from your custom player
      } 
    } as PlayerConfig<SomeCustomPlayer> }
  >
    <App/>
  </AnayticsProvider>
)

...

Using the Vime video player component:

import { VimePlayerConfig } from 'react-video-analytics'

...

return (
  <AnayticsProvider
    defaultPlayerConfig={VimePlayerConfig}
  >
    <App/>
  </AnayticsProvider>
)

...

useAnalytics

The useAnalytics hook requires a reference to your video player component. It also accepts an optional options object that allows you to customize how metrics are handled and sent to your analytics service.

Options

Prop	Type	Default	Description
send (optional)	(metrics: ReportMetrics) => void	-	Describes how to post metrics to your analytics service
videoId (optional)	string	-	Optionally supply a unique identifier for the video source being played. When this changes, a new viewId is generated
maxAttempts (optional)	number	5	Maximum number of times to attempt to send metrics before calling onFail
playerConfig (optional)	PlayerConfig	VideoPlayerConfig	The player configuration to use corresponding to the player component reference passed to useAnalytics
timeInterval (optional)	number	30000	The interval, in milliseconds, to call send when the timeupdate event is emitted
onQueue (optional)	(metrics: ReportMetrics) => void	-	Called when metrics are queued to be sent
onComplete (optional)	(metrics: ReportMetrics) => void	-	Called when metrics are successfully sent
onError (optional)	(metrics: ReportMetrics) => void	-	Called when metrics fail to be sent
onRequeue (optional)	(metrics: ReportMetrics) => void	-	Called when metrics are requeued to be sent
onFail (optional)	(metrics: ReportMetrics) => void	-	Called when metrics fail to be sent after maxAttempts

Types

ReportMetrics

Prop	Type	Description
timestamp	string	The timestamp when the metric was created
hourOfDay	number	The hour of day when the metric was created
dayOfWeek	number	The day of the week when the metric was created
action	ReportAction	The action that generated the metric
position	number	The current time (position), in seconds, of the video player
duration	number	The total duration, in seconds, of the video being played
durationBuffering	number	The time spent buffering, in seconds, whenever the video finishes buffering
browser	BrowserState	Details about the browser being used to watch the video
headers	ReportHeaders	The view and viewer ID of the video session
error (optional)	ReportError	Error details. Particularly useful when onError, onRequeue, or onFail are called
__attempts (optional)	number	The total number of attempts to send metrics. Particularly useful when onRequeue is called

ReportAction

Value	Description
complete	The video completed playing
pause	The video player was paused
play	The video player was played
quality	The video quality setting was changed
seek	The video player began seeking
buffer	The video player began buffering
time	The video player's current time was updated. By default this action occurs every 30 seconds.
setup	The initial report action
error	A playback error occurred

BrowserState

Prop	Type	Description
host (optional)	string	The host domain that the video is being watched on.
os (optional)	string	The operating system that the video is being watched on.
name (optional)	string	The name of the browser that the video is being watched on.
version (optional)	string	The browser version that the video is being watched on.

ReportHeaders

Prop	Type	Description
viewId	string	An identifier for the video's current view (session). Use this for tracking the number of views on your video.
viewerId	string	An identifier for the unique viewer (user) watching the video. Use this to track the number of unique viewers of your video.

ReportError

Prop	Type	Description
message	string	A message describing the error that occurred.
code	string	A code associated to the error that occurred.
data	object	A object containing additional details about the error that occurred.
source (optional)	unknown	A potential reference to the error's source.

Authors

• Colin Hooper - Initial work - colin-oos

See also the list of contributors who participated in this project.

License

MIT License © oos