Add Snowplow Media plugin with APIs to track media events (close #1176)

[matus-tomlein]

Issue #1176

Adds a new plugin for tracking media events using trackMediaXXX() functions. The APIs are intended to be media player agnostic and usable for all kinds of video players (in contrast with our other plugins that target YouTube, Vimeo, ...).

Tracking API

Simplified example of how one would use the plugin:

newTracker("ns1", "https://...", { plugins: [SnowplowMediaPlugin(),] });

const id = 'media-tracking-id';

startMediaTracking({ // required to call this for the tracker to keep track of the media
  id,
  player: { // properties of the media player context entity
    currentTime: 0,
    duration: 100,
  },
  session: true, // enabled by default, adds a session context entity
  pings: true, // enable ping events
  boundaries: [25, 50, 75], // enable percentage progress events and send them at the specific boundaries
});

trackMediaPlay({ id });
trackMediaPause({ id, media: { currentTime: 100 } });

// ...

endMediaTracking({ id }); // clears the state for the media tracking

Documentation

The documentation is deployed as a preview here:

1. JavaScript tracker plugin.
2. Browser tracker plugin.

The draft PR for the docs is here.

Schemas

The plugin makes use of some existing as well as new schemas:

1. It uses the media_player schema for a context entity that is added to all events and describes the current state of the media player.
2. There are a few new context entities that are currently under review in this PR:
   • media_player_session which holds an ID for all media events from the player and also some statistics about the playback computed on the tracker.
   • media_player_ad and media_player_ad_break are used to describe the currently played ads.
3. It also uses new schemas for the media player events. Instead of using a single event schema (as our other plugins do), we decided to create separate schemas for each event type. This makes it easier to filter and subscribe to specific events. There is an open PR where the event schemas are under review here.

Example app

Probably the easiest way to understand how the data looks like and how it is tracked is through an example app that I have built. The app is currently deployed at this address (this is just temporary, once reviewed I'd like to host it on Github pages for the examples repo so that anyone can inspect it to understand how media tracking works): https://snowplow-media-demo.tomlein.org/media

The app shows a media player and a table with a list of tracked events under it. The table is automatically updated as new events are tracked.

I have created a PR on the examples repository to add this app: snowplow-incubator/snowplow-javascript-tracker-examples#56

[bundlemon]

BundleMon

Files added (6)

Status	Path	Size	Limits
✅	libraries/browser-tracker-core/dist/index.mod ule.js	+24.88KB	25KB / +10%
✅	trackers/javascript-tracker/dist/sp.js	+24.02KB	25KB / +10%
✅	trackers/javascript-tracker/dist/sp.lite.js	+14.69KB	15KB / +10%
✅	trackers/browser-tracker/dist/index.umd.min.j s	+14.53KB	15KB / +10%
✅	libraries/tracker-core/dist/index.module.js	+13.35KB	15KB / +10%
✅	trackers/browser-tracker/dist/index.module.js	+3.46KB	5KB / +10%

Total files change +94.92KB 0%

Final result: ✅

View report in BundleMon website ➡️

---

Current branch size history

[jethron]

Gonna have to trust your testing on the state machine aspects in sessionStats and adTracking. 😅

Otherwise mostly looks really good, exciting plugin!

I don't have a lot of experience with the other media plugins to know if this will integrate well, so LGTM if LGT other reviewers.

[greg-el]

LGTM! Integrating this with the Vimeo plugin was smooth sailing, great job!

[jethron]

LGTM!