Easily generate and post video player metrics
To install and set up the library, run:
$ npm install --save react-video-analyticsOr if you prefer using Yarn:
$ yarn add react-video-analyticsBegin by wrapping your app with the AnalyticsProvider.
import { AnalyticsProvider } from 'react-video-analytics'
...
return (
<AnalyticsProvider>
<App />
</AnalyticsProvider>
)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} />
)
}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} />
)
}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.
| 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. |
| 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 |
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>
)
...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.
| 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 |
| 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 |
| 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 |
| 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. |
| 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. |
| 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. |
- Colin Hooper - Initial work - colin-oos
See also the list of contributors who participated in this project.
MIT License © oos