gg-ez-vp

GumGum EZ video player

Usage no npm install needed!

<script type="module">
  import ggEzVp from 'https://cdn.skypack.dev/gg-ez-vp';
</script>

README

GG EZ Video Player

Simple video player with minimal setup, intuitive API and straightforward features.

Player

Features:

  • Easy setup
  • Customizable controls (or use our slick defaults!)
  • Lightweight
  • Programmatic access to video playback APIs
  • Browser (UMD), CommonJS and ES module versions
  • VAST / VPAID Support for a single Linear Creative. Parsing is provided by dailymotion/vast-client-js. Note that at the time, only one Ad is loaded, and only Linear Creatives are played and tracked.

See the demo page

Table of contents

Installation

Browser

<!-- latest stable version -->
<script src="https://c.gumgum.com/vp/latest/gg-ez-vp.js">

<!-- beta version | synced with develop branch  -->
<script src="https://c.gumgum.com/vp/beta/gg-ez-vp.js">

<!-- or specific release, replace "1.x.x" with the release you want to use -->
<script src="https://c.gumgum.com/vp/1.x.x/gg-ez-vp.js">

Note: One of GumGum's solutions, is contextual advertising, as such, our CDN is blocked by ad blockers; if the scripts are not loading, disable the ad blocker or use an external CDN (TBD #21).

CommonJS

TODO: Installation

const GgEzVp = require('gg-ez-vp');

ES Modules

TODO: Installation

import GgEzVp from 'gg-ez-vp';

Usage

GgEzVp works by attaching itself to a unique container, ideally an empty <div> with a unique id:

<body>
    <div>
        <div class="randomContent">
            Some content
        </div>
        <div id="myVideo" class="myVideoStyles"></div>
    </div>
</body>

Then, to create a player instance:

// js
const minimalConfiguration = {
    container: 'myVideo',
    src: 'myvideo.mp4'
};

const ggEzVpInstance = new GgEzVp(minimalConfiguration);

This minimal configuration will create a unique video player instance using the defaults set by GgEzVp.

note: src and container are the only required options in the configuration object.

Customization

Options:

key defaultValue required description
container null true either a node's id or the DOM node itself where the player will be loaded to
src null true string or array of strings used to retrieve video and/or VAST
width null false by default the player will take available space, unless width is specified
height null false by default the player will take available space, unless height is specified
controls object false specific controls configurations, see Controls section below
autoplay false false whether to play the video automatically or not
volume 1 false initial volume for playback must be between 0.0 and 1
muted true false video will be muted by default
playsinline true false A Boolean attribute indicating that the video is to be played within the element's playback area.
poster null false source for an image to be used as video poster
preload 'auto' false standard HTML values for preload (none
loop false false whether to loop video or not
isVAST false false enables support for a single VAST / VPAID TAG to be parsed and used as source, will force displaying the ad controls
adControls false false forces displaying the ad controls instead of the regular contols

Controls

Besides the programmatic interaction with the player, there are also a number of controls displayed by default, they can be toggled by passing a controls property in the initial configuration. See the Styles section for information on how to customize the visuals.

Player

controlName defaultValue description
timestamp true display the current time of the video in the format [m:ss]
volume true display the volume controls (mute toggle and range input)
volumeRange true the volume range input can be hidden if only the volume button is needed
progress true display the playback progress bar, clicking on the bar will set the video currentTime to the selected percentage (except on Ads)
play true show the play/pause button
expand true show the expand to fullscreen button
timestampAd false used only for Ads, will display the remaining time in the format [Ad ss]
skip false used only for Ads, will display a skip button

Additionally, passing the adControls: true option, will display a different set of controls for Ads:

Ad Controls

controlName defaultValue description
timestampAd true display the remainingTime time of the ad in the format [Ad ss].
skip true display a skip button, pressing it will emit the 'skip' event
progress true the progress bar will display, but it won't show the scrub, nor it be possible to set the time with it
play true show the play/pause button
expand true show the expand to fullscreen button

Note: the timestamp control will be disabled when adControls is true and instead timestampAd will be displayed.

Control configuration examples

// Controls off
const controlsOffConfig = {
    container: 'myVideo',
    src: 'myvideo.mp4',
    controls: false
};

// timestamp and volume off
const customControls = {
    container: 'myVideo',
    src: 'myvideo.mp4',
    controls: {
        timestamp: false,
        volume: false
    }
};

// ad timestamp, skip and expand off
const customControls = {
    container: 'myVideo',
    src: 'myvideo.mp4',
    adControls: true, // will enable ad controls
    controls: {
        timestampAd: false,
        expand: false,
        skip: false
    }
};

Styles

To use the default styles, just include the styles.css file before loading the player's javascript:

<!-- latest version of the styles -->
<link src="https://c.gumgum.com/vp/latest/gg-ez-vp.css">

The default styles that can be overridden by any custom styles you may need:

.gg-ez-vp--play {
    background: url('/images/my-custom-play-btn.png');
    width: 40px;
    height: 40px;
}

.gg-ez-vp--progress-filled {
    background: red;
}

It is encouraged to override the styles rather than completely writing your own.

Use these selectors to override the styles:

selector component
.gg-ez-vp player container
.gg-ez-vp--viewer video element
.gg-ez-vp--controls control bar
.gg-ez-vp--timestamp current video time
.gg-ez-vp--timestamp-break bar dividing currentime / duration
.gg-ez-vp--timestamp-ad ad remaining time
.gg-ez-vp--volume volume controls container
.gg-ez-vp--volume-control volume slider container
.gg-ez-vp--volume-control-slider volume slider
.gg-ez-vp--input-range volume slider input styles
.gg-ez-vp--progress progress container
.gg-ez-vp--progress-bar progress track
.gg-ez-vp--progress-filled progress bar fill
.gg-ez-vp--progress-filled:after progress bar scrub
.gg-ez-vp--button-icon play and volume buttons
.gg-ez-vp--button-icon.mute muted state of the volume control
.gg-ez-vp--button-icon.low low volume state of the volume control (under 33%)
.gg-ez-vp--button-icon.medium medium volume state of the volume control (between 34% and 66%)
.gg-ez-vp--button-icon.high high volume state of the volume control (above 66%)
.gg-ez-vp--button-icon.play shown while video is not playing on the play control
.gg-ez-vp--button-icon.pause shown while video is playing on the play control
.gg-ez-vp--button-icon.replay shown after the video ends
.gg-ez-vp--button-icon.expand expand button icon
.gg-ez-vp--blocker invisible div that can be used to prevent clicks on VPAID/VAST thumbnails
.gg-ez-vp--slot invisible div used as VPAID slot

There are also a few modifier selectors applied to the container .gg-ez-vp:

selector description
.gg-ez-vp--no-scrub applied on adControls: true. Prevents displaying the scrub and adjusts ad styles.
.gg-ez-vp--skip applied when the skip button will be displayed
.gg-ez-vp--volume-only adjusts the styles when only the volume toggle button is displayed
.gg-ez-vp--touchscreen added when the device uses a touchscreen, this will show all enabled controls instead of activating them on hover

See src/styles.css for all styles.

Public methods

method name parameters description
destroy none removes all instance and video tag listeners, removes the player from the DOM leaving behind the original container
fullscreenToggle none toggles the fullscreen mode
getCurrentTime none returns the currentTime from the video tag, this data is also provided by the playback-progress event
muteUnmute none toggle video sound on/off
mute none disable video sound (sets volume to 0)
unmute none enable video sound (sets volume to last value)
on eventName, listenerFn attaches a listener function to either the video tag or the player instance, the function will be run every time the event is fired, see events
once eventName, listenerFn attaches a listener function to either the video tag or the player instance, the function will fire just on time, see events
pause none stop video playback
playPause none toggle pause state on/off
play none start video playback
volume float number sets the video volume, see volume configuration
getVolume float number gets the video volume
getDuration number gets the video duration

Accessible properties

All properties are read-only:

property name type description
ready boolean helps identify when the video/ad is rendered and ready for playback
dataReady boolean helps identify when the player has all the data it needs to render the video and all listeners have been set
config object current player's configuration, see Options
player DOM node current video tag, it is not recommended to interact directly with it, and instead rely on the player's methods, but is provided if necessary
dimensions object current player dimensions
VPAIDWrapper object wrapper that allows direct interaction with a VPAID creative if available, it is not recommended to interact directly with it, but it is possible if necessary

Events

Listen for any <video> tag events or GgEzVp events:

ggEzVpInstance.on('play', myPlayListener);
ggEzVpInstance.on('playback-progress', myPlaybackListener);

Listen to them only once:

ggEzVpInstance.once('play', myPlayListener);
ggEzVpInstance.once('playback-progress', myProgressListener);

The player also emits custom events to extend the video tag behavior:

event name description payload
data-ready emitted when a source for the video is received, either by configuration or after asynchronous VAST parsing undefined
playback-progress emitted when the video currentTime changes { remainingTime, readableTime, duration, currentTime, fancyCurrentTime, fancyDuration }
player-click emitted when clicks are detected inside the container element click event
pre-destroy emitted before removing listeners and the container node undefined
ready emitted when the class is ready for playback undefined
resize emitted when video tag changes either width or height { width, height }
skip emitted when the skip button is pressed undefined
expand emitted when the fullscreen is toggled boolean isFullscreen
error emitted when player encounters an error error message or object

Custom events are provided by Nano Events

VAST

VAST 3.0 is supported, thanks to dailymotion/vast-client-js for the playback of a single Linear Creative. If a VPAID is detected, it will be loaded and executed, otherwise, the player will track and emit all the events in the VAST tag.

VPAID

The player is capable of playing VPAID 2.0 if the src is a VAST tag and isVAST is set to true in the configuration. Player events will not be set immediately, instead they will be stored and attached after the VPAID has emitted the onAdLoaded event.

Event mapping

All VPAID events are emmitted, additionally, some of them will also fire a custom event:

VPAID event name GgEzVp event name
AdLoaded data-ready
AdStarted play
AdPlaying play
AdVideoStart play
AdPaused pause
AdStopped ended
AdRemainingTimeChange playback-progress
AdDurationChange playback-progress
AdVideoFirstQuartile playback-progress
AdVideoMidpoint playback-progress
AdVideoThirdQuartile playback-progress
AdVideoComplete playback-progress
AdError error

It is encouraged to use these events mapped by the player, but if you require listening to other events, all VPAID events are emitted as well with exception of the AdRemainingTimeChange event (use playback-progress instead). All data is retrieved from the VPAID creative, not the video tag itself.

Development

yarn install to install dependencies

yarn start to fire dev server and node watcher, the server can be accessed at localhost:8080, and the demo at localhost:8080/demo

See scripts section of package.json for all available scripts