https://github.com/apivideo/api.video-player-analytics
api.video player analytics module
https://github.com/apivideo/api.video-player-analytics
javascript library player video video-analytics
Last synced: 6 months ago
JSON representation
api.video player analytics module
- Host: GitHub
- URL: https://github.com/apivideo/api.video-player-analytics
- Owner: apivideo
- License: mit
- Created: 2021-03-23T16:38:45.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-30T13:08:25.000Z (about 1 year ago)
- Last Synced: 2025-03-23T19:44:53.828Z (7 months ago)
- Topics: javascript, library, player, video, video-analytics
- Language: TypeScript
- Homepage: https://api.video
- Size: 304 KB
- Stars: 18
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://twitter.com/intent/follow?screen_name=api_video) [](https://github.com/apivideo/api.video-player-analytics) [](https://community.api.video)
 
api.video player analytics module
[api.video](https://api.video) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.
## Table of contents
- [Table of contents](#table-of-contents)
- [Project description](#project-description)
- [Getting started](#getting-started)
- [Installation](#installation)
- [Method #1: requirejs](#method-1-requirejs)
- [Method #2: typescript](#method-2-typescript)
- [Method #3: imple include in a javascript project](#method-3-imple-include-in-a-javascript-project)
- [Documentation](#documentation)
- [Instantiation options](#instantiation-options)
- [Module methods](#module-methods)
- [**`ovbserveMedia(media: HTMLVideoElement)`**](#ovbservemediamedia-htmlvideoelement)
- [**`dispose()`**](#dispose)
## Project description
Javascript module to manually call the api.video analytics collector.
This is useful if you are using a video player for which we do not yet provide a ready-to-use monitoring module.
If you use one of the following video player, you should rather use the associated packaged monitoring module:
| Player | monitoring module |
| -------- | ------------------------------------------------------------------------------------------- |
| video.js | [@api.video/api.video-videojs-analytics](https://github.com/apivideo/api.video-videojs-analytics) |
| hls.js | [@api.video/api.video-hlsjs-analytics](https://github.com/apivideo/api.video-hlsjs-analytics) |
This module is compatible with React Native.
## Getting started
### Installation
#### Method #1: requirejs
If you use requirejs you can add the module as a dependency to your project with
```sh
$ npm install --save @api.video/player-analytics
```
You can then use the module in your script:
```javascript
var { PlayerAnalytics } = require('@api.video/player-analytics');
const playerAnalytics = new PlayerAnalytics({
...options // see below for available options
});
```
#### Method #2: typescript
If you use Typescript you can add the SDK as a dependency to your project with
```sh
$ npm install --save @api.video/player-analytics
```
You can then use the SDK in your script:
```typescript
import { PlayerAnalytics } from '@api.video/player-analytics'
const playerAnalytics = new PlayerAnalytics({
...options // see below for available options
});
```
#### Method #3: imple include in a javascript project
Include the SDK in your HTML file like so:
```html
...
```
Then, once the `window.onload` event has been trigered, instantiate the module with `new PlayerAnalytics()`:
```html
var playerAnalytics = new PlayerAnalytics("#target", {
...options // see below for available options
});
```
## Documentation
### Instantiation options
The analytics module constructor takes a `PlayerAnalyticsOptions` parameter that contains the following options:
| Option name | Mandatory | Type | Description |
| ------------------: | --------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| mediaUrl | **yes** | string | url of the media (eg. `https://cdn.api.video/vod/vi5oDagRVJBSKHxSiPux5rYD/hls/manifest.m3u8`) |
| userMetadata | no | ```{ [name: string]: string }[]``` | object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata/) (see **Full example** below) |
| sequence | no | ```{start: number; end?: number;} ``` | if only a sequence of the video is going to be played |
| onSessionIdReceived | no | ```(sessionId: string) => void``` | callback to be called once the session id is reveiced |
Once the module is instantiated, the following methods have to be called to monitor the playback events.
### Module methods
#### **`ovbserveMedia(media: HTMLVideoElement)`**
this method attaches event listeners to the provided HTMLVideoElement to track and analyze media playback events. No data will be collected before this method is called.
#### **`dispose()`**
his method removes all event listeners attached by `observeMedia` and cleans up any resources used for tracking media playback events.