playkit-js-vod-completion

A Kaltura Player v7 (Playkit JS) plugin that tracks how much of a VOD video a user has genuinely watched and fires events when key thresholds are crossed.

The plugin tracks unique watched coverage — rewatching a segment or seeking forward does not inflate the percentage. Only time the user actually spent watching counts.

How it works

The plugin listens to player events (PLAYING, PAUSE, SEEKING, TIME_UPDATE, ENDED) and builds a list of watched time intervals. Whenever playback stops or the user seeks, the current segment is closed and merged with the existing intervals, collapsing any overlaps. The watched percentage is computed at any point as the total length of those merged intervals divided by the video duration.

Events

| Event | When it fires | |---|---| | vod_completion_video_started | Once, on first play | | vod_completion_video_completed | Once, when unique watched coverage reaches completionThreshold |

Both events are dispatched on the player bus and can be received with player.addEventListener(...).

Configuration

| Option | Type | Default | Description | |---|---|---|---| | completionThreshold | number (0–1) | 0.9 | Fraction of the video that must be genuinely watched before vod_completion_video_completed fires. 0.9 means 90%. |

plugins: {
  vodCompletion: {
    completionThreshold: 0.8  // fire at 80% unique watched coverage
  }
}

Constraints

• VOD only — skipped automatically for live streams

Getting started with development

# First, checkout the repository and install the required dependencies
git clone https://github.com/kaltura/playkit-js-vod-completion.git

# Navigate to the repo dir
cd playkit-js-vod-completion

# Run dev-server for demo page (recompiles on file-watch, and writes to actual dist fs artifacts)
npm run dev

The dev server hosts files on port 8000. Once started, the demo is available at http://localhost:8000/.

Linter (ESLint)

Run linter:

npm run lint:check

Run linter with auto-fix mode:

npm run lint:fix

Formatting Code

Run prettier to format code

npm run prettier:fix

Type Check

Run type-check to verify TypeScript types

npm run types:check

Automated tests (Cypress)

Run all tests at once:

npm test

Run unit tests in watch mode:

npm run test:watch

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details