Ooyala Pulse SDK

Getting started

This SDK allows you to integrate ad serving from Ooyala Pulse into your HTML5 video player application using a simple event flow.

If you want your player to handle ad playback, use the OO.Pulse.Session interface.

If you want to use our ad player, use the OO.Pulse.AdPlayerController object.

With the ad player

The Pulse ad player is an hybrid HTML5/Flash player that will take care of displaying the ads for you. First, set your host using setPulseHost, then create an OO.Pulse.Session using createSession. You can now create your ad player by calling createAdPlayer.

When the content is about to start, call startSession on the ad player object, passing along your implementation of the OO.Pulse.AdPlayer.Listener.

Check out our tutorial to learn more about the use of the SDK.

For a sample integration, have a look at the video.js bridge.

Without the ad player

With OO.Pulse, first set your host using setPulseHost, then create an OO.Pulse.Session using createSession, and finally call startSession on the returned OO.Pulse.Session with your OO.Pulse.SessionListener implementation.
This listener handles all the communication between the video player and the OO.Pulse.Session.

When it is time to play a video ad, your OO.Pulse.SessionListener is sent an OO.PulseVideoAd through the startAdPlayback method.

Additionally, if you notify the SDK when content playback has been paused by calling contentPaused, you may receive a pause ad to display through showPauseAd. When content playback resumes, notify the session by calling contentStarted.

Note: At the moment, the Pulse SDK only supports linear ads, pause ads and image overlay ads.

Low Level or Core SDK

To access the older, low level API, please refer to the HTML5 Core SDK 2.x API documentation.
More documentation about creating an integration with the low level SDK can be found here: Ooyala Pulse Integration Toolkit - HTML5 SDK 2.x.

Changelog

Version 2.1.17.22.0 - November 1, 2017

FIXED

  • Clickthrough no longer triggers on mobile browsers when scrolling is performed.
  • Clickthrough is tracked properly when a midroll ad displays after an overlay ad.



Version 2.1.17.21.2 - October 25, 2017

ADDED

  • When creating a new ad player through createAdPlayer, the setAutoplayAttributes setting makes the ad player create its <video> element with the autoplay and muted attributes set. This can help you get around autoplay restrictions in recent versions of some web browers.
  • Similarly, the playInline setting makes the ad player set the playsinline attribute. This lets ads play on mobile browsers without going into fullscreen mode.

      OO.Pulse.createAdPlayer({
          adContainerElement: document.getElementById('my-id'),
          setAutoplayAttributes: true,
          playInline: true
      });

FIXED

  • Ads which don't start due to autoplay restrictions are no longer subject to playback timeouts.



Version 2.1.17.20.0 - October 12, 2017

ADDED

  • The HTML5 Ad Player provides three new events, which enable you to add functionality before or after an ad break, or before an ad starts playing:

    • LINEAR_AD_STARTING
    • AD_BREAK_STARTING
    • AD_BREAK_FINISHING

      By listening to these events and calling the defer function available in each of them, the Ad Player waits to continue until the new functionality has finished. For example, to show a trailer, after the first ad:

      var startPlayingAd = null;
      myAdPlayer.addEventListener(OO.Pulse.AdPlayer.Events.LINEAR_AD_STARTING, function(data) {
        startPlayingAd = data.defer();
      
        // Play a trailer after first ad:
        if (data.adPosition === 2) {
            // Logic to play your trailer
            videoPlayer.playTrailer(videoTrailer);
        }
      });
      
      // .. some time later, when the trailer has completed, resume normal ad playback:
      startPlayingAd();
      startPlayingAd = null;

      Additionally, LINEAR_AD_STARTING and AD_BREAK_FINISHED can inform you when the Ad Player is between a sponsor ad and a regular ad:

      myAdPlayer.addEventListener(OO.Pulse.AdPlayer.Events.LINEAR_AD_STARTING, function(data) {
        if(data.isBumperPosition) {
            console.log('Between a sponsor and ad');
        }
      });
  • preload allows you to request all third party ads before starting the session, rather than loading these types of ads during their designated ad break.

    • Note: use with caution, because impressions may be tracked by the third party as soon as they are loaded.

      var session = OO.Pulse.createSession({ }, { });
      // Ready any third party ads received before starting the session
      session.preload(function() {
        myAdPlayer.startSession(session);
      });
  • The event AD_BREAK_EMPTY fires when an ad break is discarded because it contains no playable ads.

FIXED

  • Improved reliability of mute and unmute, especially when using a shared element.
  • Impression is no longer tracked when ad autoplay is blocked by the browser.



Version 2.1.17.19.1 - September 26, 2017

CHANGED

  • If the currently selected ad is an HTML5 video ad, play returns the result of calling play on the <video> element in use. Generally, this is a Promise, which can aid in detecting whether autoplay has failed.

FIXED

  • Improved reliability of mute and unmute, especially when using a shared element.



Version 2.1.17.19.0 - September 20, 2017

ADDED

  • A new function, canAutoplay, programatically determines whether or not the shared element feature of the ad player should be used.



Version 2.1.17.18.0 - September 13, 2017

ADDED

  • LINEAR_AD_STARTED now receives an additional parameter, called selectedMediaFile, referencing the media file selected for playback for the started ad.

CHANGED

  • Modified VPAID2 implementation to increase compatibility with VPAID2 ads.



Version 2.1.17.17.0 - August 31, 2017

ADDED

  • getContainer allows you retrieve the container element which was passed to the createAdPlayer call that created the ad player.
  • getBreakPosition allows you determine the position of an ad break.

      myAdPlayer.addEventListener(OO.Pulse.AdPlayer.Events.AD_BREAK_FINISHED, function(data) {
          var adBreak = data.adBreak;
          if(adBreak.getBreakPosition() === OO.Pulse.AdBreakPosition.PREROLL) {
              console.log('Prerolls finished');
          }
      });
  • FLASH_AD_BLOCKED is fired when Flash is blocked or unavailable, and only Flash based assets are available for an ad.

CHANGED

  • AD_BREAK_FINISHED now receives the same OO.Pulse.AdBreak parameter as AD_BREAK_STARTED.
  • Third party VAST tickets with NonLinearAds elements are no longer rejected, as long as they contain no actual NonLinear elements. This allows wrappers with nonlinear tracking to be read by the SDK. Note that third party nonlinear ads are still not supported, and will not be displayed.



Version 2.1.17.16.0 - August 8, 2017

FIXED

  • Using a responsive video player could have resulted in some VPAID 2.0 ads being rendered with a width and/or height of 0.
  • Fixed a bug where, if a VPAID 2.0 ad tried to pause its video after trying to play it, but before the video started, the video would not pause.



Version 2.1.17.15.0 - August 1, 2017

CHANGED

  • Third party asset selection has been improved to ensure that VPAID ads are always selected if present, and otherwise the highest bitrate media file is always selected, taking bandwidth considerations into account.



Version 2.1.17.14.1 - July 18, 2017

ADDED

  • A new RequestSettings parameter, useVASTSkipOffset, allows you to select whether the insertion policy configured in Pulse, or the skip information present in VAST tickets, is used to determine the skip behaviour of third party ads.



Version 2.1.17.12.5 - June 20, 2017

FIXED

  • Make sure that VPAID 2.0 ads that do not clean up their assets properly are not able to play sound after they've dispatched AdStopped and content has started.



Version 2.1.17.12.2 - June 14, 2017

CHANGED

  • In order to prevent false positives, if a VPAID 2.0 ad has already fired the AdImpression event, the ad player will not fire AD_AUTOPLAY_BLOCKED.



Version 2.1.17.12.1 - June 13, 2017

CHANGED

  • If the ad player's size changes due to a page's responsive design, we will notify VPAID 2.0 ads so that they can resize their content accordingly.



Version 2.1.17.12.0 - June 13, 2017

FIXED

  • Fixed an issue where midroll ad breaks could repeat multiple times, depending on their length.



Version 2.1.17.11.2 - June 9, 2017

ADDED

  • VPAID 2.0 ads now have their volume properly changed when calls to setVolume are made.

CHANGED

  • Previously, a new pause ad would be automatically requested after one had been shown. However, if no pause ad was initially shown, no new request would be made. With this release, pause ads are always requested on content play, unless the insertion point filter does not allow it.



Version 2.1.17.10.1 - May 23, 2017

ADDED

  • A new RequestSettings parameter, enforceCacheBusting, allows you to control whether or not a cache busting parameter should be added to VAST 2.0 tracking URLs which do not include the [CACHEBUSTING] macro yet. When set to false, this parameter is not added.



Version 2.1.17.10.0 - May 15, 2017

CHANGED

  • When debug logging is enabled, all explicit error messages will be marked with a red error badge.
  • Debug log messages overall have been tweaked to improve readability.

FIXED

  • Improved compatibility with MOAT-wrapped VPAID 2.0 ads as well as ones from other providers.
  • Unsupported overlay asset types would cause the ad player to crash.



Version 2.1.17.9.3 - May 10, 2017

FIXED

  • Improved compatibility with IAS-wrapped VPAID 2.0 ads.



Version 2.1.17.9.0 - May 4, 2017

ADDED

CHANGED

  • If all media files for an ad are filtered out due to their bitrate being too high, the media file with the lowest bitrate will be selected for playback.

FIXED

  • Fixed an issue where VPAID 2.0 ads which tried to read the video element's duration before a video had been loaded would crash.



Version 2.1.17.8.0 - April 20, 2017

FIXED

  • Improved VPAID 2.0 compatibility.



Version 2.1.17.6.0 - March 30, 2017

ADDED

  • Basic support for parsing VAST 4.0 tickets.
  • Added a second signature for createAdPlayer which takes a single object, with the parameters provided as key/value pairs. This is done to reduce the length of the signature as new parameters are added. If the first argument is an instance of HTMLElement, the previous signature will still be accepted.

ADDED

  • Ad player instances can now be given an identifier upon creation, so each one can be identified in adPlayerReady callbacks.

      // Get notified of ad player creations
      OO.Pulse.adPlayerReady(function(adPlayer)) {
          if(adPlayer.getIdentifier() === 'my-player') {
              // this is the player created below
          } else {
              // this is some other player
          }
      };
    
      // Create a named ad player which can be identified above
      OO.Pulse.createAdPlayer({
          adContainerElement: document.getElementById('my-id'),
          identifier: 'my-player'
      });



Version 2.1.17.5.1 - March 20, 2017

CHANGED

  • Some VPAID 2.0 ads could change the styling of the ad player's video element, causing unexpected inconsistencies such as the video area being smaller than that of the content player.
  • Improved VPAID 2.0 ad compatibility.



Version 2.1.17.5.0 - March 10, 2017

FIXED

  • Under some circumstances, very large ad responses could fail to play back in Safari.



Version 2.1.17.4.2 - February 28, 2017

CHANGED

  • The initial bandwidth detection is now performed over HTTPS to ensure it is not blocked by the browser due to mixed content restrictions.



Version 2.1.17.4.1 - February 22, 2017

CHANGED

  • Automatic bandwidth detection is now performed as soon as the SDK is loaded, which can improve the quality of assets returned and prevent higher quality third party assests from being exluded from selection.



Version 2.1.17.4.0 - February 21, 2017

FIXED

  • Click interactions on certain VPAID 2.0 ads that did not create their own elements would not work properly.



Version 2.1.17.3.0 - February 7, 2017

ADDED

  • A callback to customize the ad player behaviour has been introduced, allowing you to implement the method by which HTML5 video ads are assigned to the relevant <video> element. This can be helpful when merely setting the src attribute of the element is not enough.

For more information, please refer to the documentation for createAdPlayer.

CHANGED

  • The Flash module now outputs log messages to the console when the pulse_debug=true request parameter is used, or OO.Pulse.debug is set to true in the console.

FIXED

  • Additional VPAID 1.0-related issues resolved.



Version 2.1.17.2.4 - February 1, 2017

FIXED

  • Some internal state could be reset when reloading the SDK script file on a page where it was previously loaded.
  • On mobile devices, when the first ad in a break timed out while loading its media file, it could cause playback failure for the remaining ads in the break.



Version 2.1.17.2.3 - January 31, 2017

FIXED

  • VPAID ads with multiple sections of video would stop playing after the first video completed.



Version 2.1.17.2.1 - January 26, 2017

FIXED

  • Under some very specific conditions, ads with passback sources would show a black screen instead of displaying the ad asset.
  • Skipping multiple ads would sometimes result in a black screen and no content playback.



Version 2.1.17.2.0 - January 25, 2017

ADDED

  • Added the ignoreSecure parameter to setPulseHost; when set to true, HTTP tracking URLs will be allowed even when the Pulse host uses HTTPS.



Version 2.1.17.1.1 - January 19, 2017

CHANGED

  • Revamped the way VPAID 2.0 ads are played in order to increase the number of compatible ads.
  • If a VPAID 2.0 ad creates its own <video> element, and the ad player detects that autoplay on such an element was blocked (common on mobile devices), we will fire AD_AUTOPLAY_BLOCKED.



Version 2.1.17.1.0 - January 17, 2017

CHANGED

  • Reject VAST tickets containing multiple creatives as unsupported.
  • Allow mixed source assets (such as HTTPS assets on an HTTP page) in the Flash ad player module.

FIXED

  • Some VPAID ads' own skip buttons would not function properly.
  • VPAID ads which were loaded, but did not start playing on time, would freeze content playback.



Version 2.1.16.26.1 - December 28, 2016

FIXED

  • Fixed an issue where skipping VPAIDs would result in playback being blocked.



Version 2.1.16.25.3 - December 22, 2016

CHANGED

  • When using the ad player, the duration of an ad will be read from the selected media file rather than the VAST ticket.



Version 2.1.16.24.2 - December 8, 2016

FIXED

  • TypeError was sometimes thrown when calling stopSession.



Version 2.1.16.24.1 - December 7, 2016

FIXED

  • Add missing impression tracking to overlay ads.



Version 2.1.16.24.0 - December 1, 2016

FIXED

  • Fixed issue with a potential loss of Pulse creative-level tracking events after loading a third party ad.



Version 2.1.16.23.1 - November 23, 2016

FIXED

  • The ad interaction event was not tracked properly on pause ads.



Version 2.1.16.23.0 - November 15, 2016

FIXED

  • The Flash VPAID player could throw errors when the setVolume API was used before the ads were ready.



Version 2.1.16.22.1 - November 10, 2016

ADDED

  • Automatic bandwidth detection now allows the SDK to select the best media files to display (if no maxBitRate is provided in the request settings), depending on a user's connection bandwidth.



Version 2.1.16.22.0 - November 7, 2016

ADDED

  • The Pulse SDK now automatically displays companion banners linked to your linear ads, if HTML div(s) with the appropriate id tag(s) are found on the page. No additional configurations in your integration are necessary to activate this functionality. Note that you have to have companion banner ads available in your Pulse account.
  • mute and unmute APIs: mute/unmute the ad player
  • getVolume returns the current ad player's volume



Version 2.1.16.21.0 - October 25, 2016

FIXED

  • openClickthrough is only called if the clickthrough URL to open is not null.
  • Catch internal passback exceptions that could hang the SDK.



Version 2.1.16.20.5 - October 12, 2016

FIXED

  • Parser discarded ticket if ad had a clickTracking URL but no clickThrough URL.



Version 2.1.16.20.2 - October 4, 2016

FIXED

  • Improved API logging. Log messages are sent out for common API calls to spot integration problems.



Version 2.1.16.20.0 - October 3, 2016

FIXED

  • Catch all Javascript VPAID exceptions to avoid crashes.



Version 2.1.16.19.2 - September 26, 2016

ADDED

  • Support for ad preview: ad preview allows you to preview the ad you want (through its ad ID) and make the Pulse ad player display it as a preroll, without doing any tracking. There are two ways of doing it.
    • Adding pulse_preview=the-pulse-ad-id-you-want-to-preview to the URL of your page with the ad ID you would like to preview.
    • Using the new request setting pulse_preview with the ad ID you would like to preview.



Version 2.1.16.19.1 - September 21, 2016

FIXED

  • VPAID ad sometimes fails because we try to play it as a video file.



Version 2.1.16.19.0 - September 20, 2016

FIXED

  • Correctly track pause ads impressions.
  • Catch local storage exceptions thrown when browsing in private mode.



Version 2.1.16.18.1 - September 15, 2016

ADDED

CHANGED

  • Errors which occur during ad requests, including errors requesting and parsing third party VAST tickets, are now logged in debug mode.



Version 2.1.16.18.0 - September 7, 2016

ADDED

  • Added the SESSION_STARTED event, which fires when the first preroll starts playing, if prerolls are available, or when the content first starts playing, if prerolls are not available.



Version 2.1.16.17.0 - August 22, 2016

ADDED

  • To enable debug logs from the Pulse SDK, you can now add pulse_debug to your page's query string parameters. For example, mysite.com/mypage?pulse_debug will activate debug on mysite.com/mypage.

FIXED

  • Fixed an issue in MS Edge/IE 11 where two ad breaks containing Flash ads could not played in a row (the second one would fail).
  • Ignore comments in VAST tickets. This could cause issues when parsing VAST wrapper tickets.



Version 2.1.16.16.0 - August 10, 2016

FIXED

  • Enforce a timeout on VPAID 2 ads that won't fire the adStopped event in time.
  • Hide the iframe used to display VPAID 2 ads. It could cause display problems with some ads.



Version 2.1.16.15.0 - August 1, 2016

ADDED

  • Session extension : new method extendSession on the Pulse session object. Session extension can be used to dynamically add new ads in a session, with the same API as createSession.

      //This call can be done anytime while the content is playing
      //Let's add a midroll at 50 seconds playback
      myRequestSettings.linearPlaybackPositions = [50];
      myExistingSession.extendSession(myContentMetadata, myRequestSettings, function(){
          console.log("Session extended!");
          });

FIXED

  • Added a black background to the video element used to play ads so that ads with a different aspect ratio than the content display properly.
  • Catch exceptions coming from VPAID ads when they are being stopped.
  • Do not hide the HTML5 video used by the ad player when it is being shared with the content player.



Version 2.1.16.14.6 - July 19, 2016

CHANGED

  • Add additional safeguards to prevent errors due to misbehaving VPAID2 ads.



Version 2.1.16.14.4 - July 15, 2016

CHANGED

  • Do not reject VAST3 companion ads with no required attribute.

FIXED

  • Progress tracking events would not merge properly under some circumstances. Now fixed.
  • Fixed an issue where Flash VPAIDs could be stopped before performing their AdVideoComplete logic.



Version 2.1.16.14.1 - July 14, 2016

CHANGED

  • Ad clickthrough is now triggered by listening for the touchend event on mobile devices.



Version 2.1.16.14.0 - July 12, 2016

ADDED

  • Support for pause ads through the PauseAd interface.

FIXED

  • Errors will no longer be thrown if you notify the session of content events after a session request fails.
  • Ad objects provided in LINEAR_AD_STARTED events will no longer have their properties cleared when the ads have finished.



Version 2.1.16.13.0 - June 27, 2016

FIXED

ADDED

  • New AD_SESSION_FINISHED event, fired when both the content and the postrolls are done playing.



Version 2.1.16.12.0 - June 13, 2016

FIXED

  • Accept third-party VPAID VAST tickets with no impression tracking URLs.
  • Fixed a bug where empty adParameters in VAST tickets were not correctly parsed.



Version 2.1.16.11.0 - June 2, 2016

ADDED

  • Support for protocol-relative URLs in OO.Pulse.setPulseHost.
  • A DOM event pulseready is now fired when the Pulse SDK is ready to be used. This event can be useful when the SDK is loaded dynamically.

      document.addEventListener('pulseready', function(){
                  console.log("The Pulse SDK is ready \\o/");
                  //OO.Pulse can now safely be used
                  OO.Pulse.createSession(...);
              });



Version 2.1.16.10.3 - May 23, 2016

ADDED



Version 2.1.16.10.0 - May 16, 2016

FIXED

  • Fixed incorrect timeSpent tracking URL.



Version 2.1.16.9.1 - May 12, 2016

FIXED



Version 2.1.16.9.0 - May 10, 2016

FIXED



Version 2.1.16.8.1 - April 20, 2016

ADDED

  • Added a Flash module for third party VPAID ticket requests which fail without proper CORS configuration.



Version 2.1.16.8.0 - April 18, 2016

ADDED

CHANGED

  • Bugfix: VPAID 2.0 ads could still be loaded despite being cancelled on very slow connections.
  • Bugfix: SHOW_SKIP_BUTTON event was not fired.



Version 2.1.16.7.0 - April 6, 2016

CHANGED



Version 2.1.16.5.0 - March 23, 2016

The OO.Pulse.AdPlayer object allows you to easily integrate Pulse with your video player.

CHANGED

ADDED

  • The OO.Pulse.AdPlayer object allows you to easily integrate Pulse with your video player. The ad player handles all the ad playback and supports video ads, VPAID 1.0 and VPAID 2.0 linear ads.

      //Create a Pulse session and an ad player.
      var session = OO.Pulse.createSession(requestSettings, contentMetadata);
      var adPlayer = OO.Pulse.createAdPlayer(adContainerDiv, uiOptions);
      //When the content starts
      adPlayer.startSession(session, myAdPlayerListener);
  • The OO.Pulse.AdBreak interface allows you to get the total and remaining number of playable ads in an ad break.

    startAdPlayback: function(ad, timeout) {
      var currentAdPosition = this.currentAdBreak.getPlayableAdsTotal() - this.currentAdBreak.getPlayableAdsRemaining() + 1;
      console.log('Playing ad ' + currentAdPosition + '/' + this.currentAdBreak.getPlayableAdsTotal());
      ...
    }
  • OO.Pulse.AdBreak.stopAdBreak forcefully stops an ad break. If called inside OO.Pulse.SessionListener.startAdBreak, it will completely prevent the ads in that ad break from being displayed.



Version 2.1.16.3.0 - February 15, 2016

ADDED

  • Added adSkipped method to OO.Pulse.VideoAd, allowing you to indicate that the user activated a close or skip button for the currently playing ad.



Version 2.1.16.2.0 - February 4, 2016

ADDED

  • Added setLogListener method to OO.Pulse, allowing you to set a listener to be notified when there are error or warning messages.

    These messages can be useful to determine why ads may not be displaying.

    OO.Pulse.setLogListener(function(logItem) {
      console.log("Received Core Log Message: " + logItem.message);
    });



Version 2.1.15.24.0 - December 17, 2015