USING SMART VIDEO PLAYER

Adsolutions / Documentation  / USING SMART VIDEO PLAYER

USING SMART VIDEO PLAYER

The SmartVideoPlayer allows for auto-initiated delivery of video across devices to play in-line within your ads.
For example, on desktop environments that supports inline, auto-initiated HTML5 Video playback, it will default to using the standard VideoJS player, whereas, on mobile and tablet devices that do not support inline, auto-initiated HTML5 Video playback (such as iOS and certain Android devices), it will default to delivering a video like experience by using HTML5 Canvas to render frame by frame. This solves a major issue on mobile devices by circumventing the lack of auto initiated inline video playback, and provides a consistent, device and tag agnostic video experience.

The SmartVideoPlayer API
Current version: 1.0.0 (4 Nov 2015)

API methods and configuration options
Constructor

createPlayer({…}) –  Initializes the player and loads the first video. Returns reference to the player. The player automatically pauses video when the page goes out of view (browser tab switch, browser minimize), and resumes video when page returns into view.

  • mode {string} [inlineAutoplay] –
    • inlineAutoplay – Default player mode. Chooses player that supports both inline playback and autoplay based on the user’s current device.
      inline – Chooses player that supports inline playback based on the user’s current device. If autoplay is true, mode switches back to inlineAutoplay.
    • native – Chooses Video.js player which plays using native HTML5 video tag. For devices such as iPhone, video plays in native full-screen player. On devices such as iPad, video will play inline. If autoplay is true, mode switches back to inlineAutoplay.
  • container {DOMElement|string} – DOMElement reference or ID of the parent node of SmartVideoPlayer.
  • width {number} – Pixel width of the player.
  • height {number} – Pixel height of the player.
  • skin {string=} – Optional CSS class name of the VideoJS skin (see Skinning). If empty, uses default VideoJS 5.0.0 styles.
  • autoplay {boolean} [true] – Plays muted video immediately after creating the player. Set to false to only play after play({auto: true}) is called or after the user clicks to play.
  • name {string=} – When using a single video, not from a Content Collection, optionally define a name to include in the video tracking events. No need to include the word “Video” here since it’s already part of video tracking names. This is also used by the new ONE platform asset inspector to pre-define video events prefixed with this name.
  • content {string=} – When using a video from a Content Collection, specify the name of the collection. This is also used by the new ONE platform asset inspector to pre-define video events prefixed with this collection name and the tracking ID of each collection item.
  • contentItem {Object=} – When using a video from a Content Collection, include a reference to the item in the collection so the Tracking ID is used in the video tracking events.
  • poster {string} – URL of the poster frame.
  • src {Object} – Group containing the various source files.
    • ogv {string} – URL of the OGV video that plays inline on iPhones. Note this URL must be on the same domain as the ad, or on a domain with an Access-Control-Allow-Origin header. Required if player.mode remains the default of inline.
    • mp4 {string} – URL of the MP4 video that plays when supported.
    • webm {string} – URL of the WebM video that plays when supported.

Methods

  • on(eventName, handler) – adds an event listener
  • off(eventName, handler) – removes an event listener.
  • load({…}) – Re-uses the same player but loads a new video. If autoplay was set to true in the call to createPlayer(), this autoplays the new video.
    • name {string=} – Optionally define a name to include before each video tracking events. No need to include the word “Video” since it’s already part of video events.
    • content {string=} – When using a video from a Content Collection, specify the name of the collection.
    • contentItem {Object=} – When using a video from a Content Collection, include a reference to the item in the collection so the Tracking ID is used in the video tracking events.
    • poster {string} – URL of the poster frame.
    • src {Object} – Group containing the various source files.
      • ogv {string} – URL of the OGV video that plays inline on iPhones. Note this URL must be on the same domain as the ad. Required if player.mode remains the default of inline.
      • mp4 {string} – URL of the MP4 video that plays when supported.
      • webm {string} – URL of the WebM video that plays when supported.
  • play({…})
    • auto {boolean=} [false] – Set to true if tracking should be bypassed.
    • bigPlayButton {boolean=} [false] – Set to true to log “Video Play”. (A normal call to play() logs “Video Start” on first call, or “Video Resume” on subsequent calls.)
  • pause({…})
    • auto {boolean} [false] – Set to true if tracking should be bypassed.
  • stop()
  • mute({…})
    • auto {boolean} [false] – Set to true if tracking should be bypassed
  • unmute({…})
    • auto {boolean} [false] – Set to true if tracking should be bypassed.
  • toggleFullscreen()
  • remove() – remove from parent DOM element.
  • appendTo(DOMElement|string) – move new parent DOM element by reference or ID.
  • destroy()– remove() and destroy internal state.

Getter/Setter Methods
These methods jive with Video.js.

  • el() – returns the player DOM element containing all “vjs-” prefixed CSS class names.
  • currentTime() – returns the current time in seconds.
  • currentTime(newTime) – sets the new time in seconds and seeks to that position.
  • dimensions(width, height) – sets the player size to new width and height.
  • duration() – the duration in seconds.
  • isFullscreen()
  • muted() – returns true if video is muted, false if not. Use methods mute() and unmute() to mute with optional event blocking.
  • paused()– returns true if video is not playing, false if video is playing.
  • videoWidth() – gets the width of the video source, after LOADED_METADATA.
  • videoHeight() – gets the height of the video source, after LOADED_METADATA, e.g.:
smartPlayer.on(
  SmartVideoPlayer.event.LOADED_METADATA, 
  function() { 
    console.log(smartPlayer.videoWidth(), smartPlayer.videoHeight());
  });

Properties

  • playerType {string} – which player was used, either:
    • SmartVideoPlayer.playerType.VIDEO_JS, or
    • SmartVideoPlayer.playerType.MOBILE_INLINE_VIDEO_PLAYER
  • player {Object} – the instance of either the Video.js player, or MobileInlineVideoPlayer. Use this to make direct method calls on that player once it is ready, e.g.:
smartPlayer.on(
  SmartVideoPlayer.event.READY, 
  function() { 
    if (smartPlayer.player.dimensions) {
      var vjs = player.player;
      console.log(vjs.remoteTextTracks());
    }
  });

Events
These events are dispatched by SmartVideoPlayer via the on(event, handler) method:

  • SmartVideoPlayer.event.READY – wait to invoke any methods until this event fires, since the players are loaded asynchronously (either Video.js, or MobileInlineVideoPlayer).
  • SmartVideoPlayer.event.LOADED_METADATA – once this event fires, the videoWidth() and videoHeight() getter methods are available for use.
  • SmartVideoPlayer.event.PLAY – video starts playing
  • SmartVideoPlayer.event.PLAY_BUTTON_CLICK – big play button clicked
  • SmartVideoPlayer.event.PAUSE
  • SmartVideoPlayer.event.ENDED
  • SmartVideoPlayer.event.SEEKED
  • SmartVideoPlayer.event.VOLUME_CHANGE
  • SmartVideoPlayer.event.FULLSCREEN_CHANGE
  • SmartVideoPlayer.event.TIME_UPDATE/li>

See API Events in action using this test utility: http://onecreative.aol.com/view/174971/c1d8dfd394af4c42b04d1842fb6b389c

Platform Video Tracking Events
SmartVideoPlayer uses the VideoTracking module to log all expected video tracking events in the platform:

  • Video Start – When a video starts, regardless of user initiated or auto-initiated.
  • Video Play – Logged only when the user presses the big play button or when .play({bigPlayButton: true})is called. Bypassed when.play({auto: true}) is called.
  • Video Pause – Logged when the video is paused. Bypassed when.pause({auto: true}) is called.
  • Video Resume – Logged when video is played after pausing.
  • Video Seek – Logged when the user moves the seek bar or when the currentTime(…) setter method is called.
  • Video Mute – Logged when the user presses the mute button. Bypassed when .mute({auto: true}) is called.
  • Video Unmute – Logged when the user presses the mute button. Bypassed when.mute({auto: true}) is called.
  • Video Fullscreen – Logged when the video enters fullscreen state.
  • Video Fullscreen Return – Logged when the video exits fullscreen state. But, the platform currently does not create this event in the Events panel, so it’s not recorded. That is dependent on https://jira.ops.aol.com/browse/PL-310.
  • Video First Quartile – Logged when the video reaches 1/4 of the duration.
  • Video First Midpoint – Logged when the video reaches 1/2 of the duration.
  • Video Third Quartile – Logged when the video reaches 3/4 of the duration.
  • Video Complete – Logged when the video reaches the end.
  • Video Replay – Logged when the same video is played a second time.

See Video Events logged using this test utility: http://onecreative.aol.com/view/174971/c1d8dfd394af4c42b04d1842fb6b389c

Basic Inline Autoplay

Inline autoplay a single video, using the default skin, with a name used in the video tracking, attached to a div referenced by smartPlayerContainer:

DTECH.require(['SmartVideoPlayer'], function() {
  var smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
    container: smartPlayerContainer,
    width: 300,
    height: 250,
    poster: 'video_300x250.jpg',
    src: {
      ogv: 'video.ogv',
      mp4: 'video.mp4',
      webm: 'video.webm'
    }
  });

Add Custom CSS Skin
Create a custom Video.js skin in CSS using a <link> or <style> tag then apply it to the player using the skin property. 

ADTECH.require(['SmartVideoPlayer'], function() {
  var smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
    skin: 'vjs-my-custom-skin',
    container: smartPlayerContainer,
    width: 300,
    height: 250,
    poster: 'video_300x250.jpg',
    src: {
      ogv: 'video.ogv',
      mp4: 'video.mp4',
      webm: 'video.webm'
    }
  });
});

Add Video Tracking Name
If you have multiple videos on a page and want a descriptive name to prefix all of the “Video Start”, “Video Pause” etc events, add it using the name property. Then follow it with a commented-out line of code that, when the file is saved/uploaded, tells the ONE Creative platform to create video events in the Events panel prefixed with that name.

ADTECH.require(['SmartVideoPlayer'], function() {
  var smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
    name: 'ADSOLUTIONS',
    container: smartPlayerContainer,
    width: 300,
    height: 250,
    poster: 'one_300x250.jpg',
    src: {
      ogv: 'video.ogv',
      mp4: 'video.mp4',
      webm: 'video.webm'
    }
  });
});
// When the platform scans this file, the next line tells it to
// register video events using the "ADSOLUTIONS" name:
// ADTECH.registerVideoPlayer({}, 'ADSOLUTIONS');
// (This line will not be needed when using the new ONE core library instead of ADTECH.)

Inline Autoplay from Content Collection
Inline autoplay a video from a content collection by defining the collection, registering video events for the collection, then using the load({…}) method to reload separate videos into the same player.

ADTECH.ready(function() {

  // Define a content collection to contain 2 videos.
  var collection = ADTECH.getContent('My Videos', [{
    "mp4": "adsolutions_medium.mp4",
    "webm": "adsolutions_medium.webm",
    "ogv": "adsolutions_medium_3.ogv",
    "poster": "adsolutions_poster_640x351.jpg"
  }, {
    "mp4": "DS5_Showroom_High.mp4",
    "webm": "DS5_Showroom.webm",
    "ogv": "DS5_Showroom_High_qual8.ogv",
    "poster": "DS5_poster.jpg"
  }]);

  // The next commented-out line is needed to tell the platform to make video events    
  // in the Events panel for all items in the "My Videos" content collection:
  // ADTECH.setReportingIdFromContent('My Videos', {}, {});
  // (That line will not be needed when using the new ONE core library) 

  ADTECH.require(['SmartVideoPlayer'],
    function(SmartVideoPlayer) {

      var smartPlayerContainer = document.querySelector('#smartPlayerContainer');

      var firstItem = collection[0];

      // Create the player, and load/autoplay the first video.
      var smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
        container: smartPlayerContainer,
        width: 300,
        height: 250,
        poster: firstItem.poster,
        content: 'My Videos',
        contentItem: firstItem,
        src: {
          ogv: firstItem.ogv,
          mp4: firstItem.mp4,
          webm: firstItem.webm
        }
      });

      // Keep track of which video is playing.
      var currentVideoIndex = 0;

      // When the video ends, automatically play the next video in the collection.
      smartPlayer.on(SmartVideoPlayer.event.ENDED, playNext);

      function loadAndPlay(index) {
        var contentItem = collection[index];

        smartPlayer.load({
          src: {
            mp4: contentItem.mp4,
            webm: contentItem.webm,
            ogv: contentItem.ogv
          },
          poster: contentItem.poster,
          content: 'My Videos',
          contentItem: contentItem
        });

        currentVideoIndex = index;
      }

      function playNext() {
        if (currentVideoIndex === collection.length - 1) {
          // End at the last video poster frame.
        } else {
          loadAndPlay(currentVideoIndex + 1);
        }
      }
    });
});

Implement custom in-page visibility logic to auto-pause/auto-resume

The player automatically pauses video when the page as a whole goes out of view (browser tab switch, browser minimize), and resumes video when page returns into view — without logging any video events.

However an ad developer may want to define custom logic to determine when the player itself leaves view within the same page, and pause the video, then resume it when the player enters view on the same page.

  1. Create a player that does not automatically start playing the first video:
var smartPlayer;
ADTECH.require(['SmartVideoPlayer'], function() {
  smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
    container: smartPlayerContainer,
    width: 300,
    height: 250,
    autoplay: false,
    poster: 'adsolutions_300x250.jpg',
    src: {
      ogv: 'adsolutions.ogv',
      mp4: 'adsolutions.mp4',
      webm: 'adsolutions.webm'
    }
});

2. When the player enters view on the page, call this to play the video and bypass logging:

smartPlayer.play({auto: true});

3. When the player leaves view on the page, pause the video and bypass logging:

var pausedOutOfView = false;
if (!smartPlayer.paused()) {
  smartPlayer.pause({auto: true});
  pausedOutOfView = true;
}

4. When player returns into view, resume the video and bypass the tracking with:

if (pausedOutOfView) {
  smartPlayer.play({auto: true});
}

Resize player to fit dimensions of video
Set the dimensions of the video player to exactly fit the size of the video loaded, by waiting for the LOADED_METADATA event.

ADTECH.require(['SmartVideoPlayer'], function() {
  var smartPlayer = ADTECH.modules.SmartVideoPlayer.createPlayer({
    container: smartPlayerContainer,
    width: 300,
    height: 250,
    poster: 'adsolutions_300x250.jpg',
    src: {
      ogv: 'adsolutions.ogv',
      mp4: 'adsolutions.mp4',
      webm: 'adsolutions.webm'
    }
  });
  smartPlayer.on(SmartVideoPlayer.event.LOADED_METADATA, function() { 
    smartPlayer.dimensions(
      smartPlayer.videoWidth(), 
      smartPlayer.videoHeight());
  });
});

Which devices and situations will use the MobileInlineVideoPlayer module

SmartVideoPlayer defaults to native HTML5 Video playback using Video.js where possible, but uses the MobileInlineVideoPlayer when needed:

Screen Shot 2016-05-24 at 11.31.16

When mode is SmartVideoPlayer.mode.NATIVE, Video.js is used in all scenarios except when autoplay is set to true – mode is automatically switched back to INLINE_AUTOPLAY. To force native playback, also set autoplay to false.

Behavior in MRAID environment is currently the same. In a future version, SmartVideoPlayer could check if autoplay is natively supported in the WebView and could use Video.js.

Feature limitations.

  • The player is aware of whether the page is in view or not, but is not currently aware of when it is scrolled into and out of view. The ad developer would need to be add such detection, and call methods .play({auto: true}) when scrolled into view, and .pause({auto: true}) when scrolled out of view.

  • The MobileInlineVideoPlayer player does not currently support retina display quality (using a <canvas> that is 4x the total area).

  • In the fork of OGV.js used by MobileInlineVideoPlayer – when un-muting, audio artifacts increase after seeking. This issue is resolved in OGV.js 1.0 with its use of Web Workers to decode audio on a separate thread. However version 1.0 does not yet support autoplay on iOS, which is why we use an older fork. The planned OGV.js 1.1 release will support autoplay, so the audio quality should improve when that is available. Watch this issue: https://github.com/brion/ogv.js/issues/112

  • When MobileInlineVideoPlayer is used on iOS, the fullscreen button currently expands the video player to fill the size of the iframe, proportionally using letterboxing, since iOS does not support the HTML5 Fullscreen API. This sprint we will modify RMLib to expand the container to as large as it can get.

    • If we need to go truly full screen, we can add a feature thatwhere to MP4 video using native HTML5 video playback, starting from the same timecode. We verified this works, but this would require a separate video file download.