react-video-analytics v0.1.3

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

Types

PlayerConfig<Player = unknown>

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

Types

ReportMetrics

ReportAction

BrowserState

ReportHeaders

ReportError

Authors

• Colin Hooper - Initial work - colin-oos

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

License

MIT License © oos