Namespace: Pulse

OO. Pulse

The Ooyala Pulse SDK.

This class is used to request ad sessions from Ooyala Pulse.
An ad session contains all the ads that should be played along with a specific piece of content.

When your application has content which it wants to display alongside advertisements, it requests a new ad session using OO.Pulse#createSession. The Pulse ad player can be used to play the session

For access to the low-level Core API, refer to videoplaza.adrequest.AdRequester and videoplaza.tracking.Tracker.

Namespaces

CustomBehaviours

Members


<static> AdBreakPosition :string

Ad break positions which can be read from OO.Pulse.AdBreak.

Type:
  • string
Properties:
Name Type Default Description
PREROLL string preroll

The ad break plays before the main content.

MIDROLL string midroll

The ad break plays during the main content.

POSTROLL string postroll

The ad break plays after the main content.


<static> AutoplayMode :string

Autoplay modes that can be returned from OO.Pulse#getAutoplayMode.

Type:
  • string
Properties:
Name Type Default Description
NORMAL string normal

No special settings should be required to support autoplay of ads.

MUTED string muted

The browser may block autoplay of ads unless they are muted.

To get around this, you can pass true to the setAutoplayAttributes parameter of OO.Pulse.AdPlayerSettings when creating an Ad Player instance.

A viewer may still have blocked autoplay in their browser settings. If you want to be absolutely sure that autoplay works as expected, you should use a shared element.

SHARED string shared

The browser may block autoplay of ads unless the user interacts with it, normally by clicking play on the ad.

To get around this, you can pass your content <video> element to the sharedVideoElement parameter of OO.Pulse.AdPlayerSettings when creating an Ad Player instance.


<static> ContentForm :string

Potential content form values passed to OO.Pulse#createSession, used to determine the ad insertion policy.

Type:
  • string
Properties:
Name Type Default Description
SHORT_FORM string shortForm

Short form content. Typically used for news summaries, game highlights and the like.

LONG_FORM string longForm

Long form content. Typically used for feature films, TV series, complete games, and the like.


<static> InsertionPointType :string

All valid types you can pass in the insertionPointFilter list in requestSettings, as an argument to OO.Pulse#createSession. These will determine when the received ads are to be played.

Type:
  • string
Properties:
Name Type Default Description
ON_BEFORE_CONTENT string onBeforeContent

Request ads to be played before the content, or 'preroll' ads.

PLAYBACK_POSITION string playbackPosition

Request ads to be played during the content, or 'midroll' ads; don't forget to specify which positions the ads are to be played at, in the linearPlaybackPositions field. Additionality, specifying positions in the nonLinearPlaybackPositions field will request overlay ads.

ON_CONTENT_END string onContentEnd

Request ads to be played after the content, or 'postroll' ads.

ON_PAUSE string onPause

Request ads to be played when the content is paused.

PLAYBACK_TIME string playbackTime

Request ads to be displayed based on the content duration.


<static> maxBitRate :number

Default maximum bitrate for the ads (in kbps/s). This value is used only if the request setting OO.Pulse.RequestSettings maxBitRate isn't set AND if automatic bandwitdh detection has failed/ timed out.

Type:
  • number
Default Value:
  • 800

<static> PreferredMediaFormat :string

Modes to determine which media file format should be at the top of the ad's eligible media files.

Type:
  • string
Properties:
Name Type Default Description
WEBM string video/webm
MP4 string video/mp4
OGG string video/ogg

<static> SeekMode :string

Modes which determine how the session behaves when a viewer seeks past one or more midroll ad breaks.

Type:
  • string
Properties:
Name Type Default Description
IGNORE string ignore

Do not enforce midroll ad breaks to be played. This is the default.

PLAY_FIRST string playFirst

If the viewer seeks past one or more ad breaks, the first one is played before content resumes.

PLAY_LAST string playLast

If the viewer seeks past one or more ad breaks, the last one is played before content resumes.

PLAY_ALL string playAll

If the viewer seeks past one or more ad breaks, all of them are played before content resumes.


<static> Version :string

Pulse SDK version.

Type:
  • string

Methods


adPlayerReady(callback)

Listen to an ad player creation.

Parameters:
Name Type Description
callback

The callback to be called when an ad player is created. The ad player will be given to it as a parameter

Example
OO.Pulse.adPlayerReady(function(adPlayer){
     var myAdPlayer = adPlayer;
  })

canAutoplay()

Deprecated. Please use OO.Pulse#getAutoplayMode instead.

Detect whether autoplay on <video> elements is supported or not.

If the method returns false, you should pass your content player's <video> element in the sharedVideoElement parameter of OO.Pulse#createAdPlayer.

Browser detection is done using the bowser library. bowser is (c) Dustin Diaz 2015.

Returns:

Whether or not autoplay is supported.

Type
boolean

createAdPlayer(settings)

Create an ad player.

Parameters:
Name Type Description
settings OO.Pulse.AdPlayerSettings

Settings for the ad player instance.

Returns:
Type
OO.Pulse.AdPlayerController

createAdPlayer(adContainerElement, uiOptions, sharedVideoElement, customBehaviours)

Create an ad player.

Parameters:
Name Type Description
adContainerElement HTMLElement

HTML div where the player is located.

uiOptions OO.Pulse.UiOptions

Player UI options.

sharedVideoElement HTMLVideoElement

HTML5 video element that the ad player should use to render the HTML5 videos. This is useful on mobile devices which impose autoplay and other restrictions on such elements.

customBehaviours OO.Pulse.CustomBehaviours

Optional callbacks used to customize the ad player behaviour.

Returns:
Type
OO.Pulse.AdPlayerController

createSession(contentMetadata, requestSettings)

Request a new ad session.

Parameters:
Name Type Description
contentMetadata OO.Pulse.ContentMetadata

Information about the content which a requested ad session is to be played with, as well as information targeting the desired campaign(s).

requestSettings OO.Pulse.RequestSettings

Information about the environment in which the requested ad(s) will play.

Returns:
Type
OO.Pulse.Session

getAutoplayMode()

Get a recommendation from the SDK on how to handle autoplaying ads, depending on the browser being used.

Returns:

The recommended way to ensure ads can play automatically.

Type
OO.Pulse.AutoplayMode

setLogListener(logCallback)

Set a listener to receive low-level log messages about errors, warnings and the like, which may be dispatched during ad or tracking requests.

Parameters:
Name Type Description
logCallback videoplaza.LogItem~logItemCallback

A callback which receives logging information.


setPulseHost(pulseHost, deviceContainer, persistentId, ignoreSecure, disableFlash)

Set your Pulse account hostname, and optionally device container, persistent ID, and secure mode.

Keep in mind that, by default, if an HTTPS Pulse host is used, any tracking URLs which do not also use HTTPS will be ignored. This includes global trackers and third party tracking URLs.

Parameters:
Name Type Description
pulseHost string

Full hostname of the Ooyala Pulse account to use.

deviceContainer string

Ooyala Pulse device container.

persistentId string

Ooyala Pulse persistent ID; used for unique user tracking.

ignoreSecure boolean

If true, allow tracking HTTP URLs when using an HTTPS Pulse host. If not passed, such URLs are not allowed when using HTTPS.

disableFlash boolean

If true, no Flash assets will be loaded, OO.Pulse.AdPlayer.Settings#RenderingMode will be set to HTML5_ONLY.

Type Definitions


AdPlayerSettings

Type:
  • Object
Properties:
Name Type Description
adContainerElement HTMLElement

HTML div where the player is located.

uiOptions OO.Pulse.UiOptions

Player UI options.

sharedVideoElement HTMLVideoElement

HTML5 video element that the ad player should use to render the HTML5 videos. This is useful on mobile devices which impose autoplay and other restrictions on such elements.

customBehaviours OO.Pulse.CustomBehaviours

Optional callbacks used to customize the ad player behaviour.

identifier string

A custom string allowing you to identify each ad player instance.

setAutoplayAttributes boolean

Attempt to allow autoplay by setting the autoplay and muted attributes on the ad player's <video> element.

playInline boolean

Set the playsinline attribute on the ad player's <video> element, allowing ads to play without going to fullscreen on some mobile browsers.


ContentMetadata

Type:
  • Object
Properties:
Name Type Description
category string

Content category is used by Ooyala Pulse to target ads and determine the ad insertion policy. The content category can be represented by either its unique id or one of its aliases set in Ooyala Pulse.

contentForm OO.Pulse.ContentForm

Content form is used to determine the ad insertion policy.

id string

Ooyala Pulse content id. Id is used to identify the content to 3rd parties.

contentPartner string

Ooyala Pulse content partner. Content partners can be used by Ooyala Pulse to target ads. The content partner can be represented by either its unique id or one of its aliases set in Ooyala Pulse.

duration number

This value cannot be negative.

flags Array.<string>

Ooyala Pulse flags. Since flags override Ooyala Pulse's ad insertion policy, they should be used with caution. For more information talk to your contact at Ooyala. Supported flags: nocom, noprerolls, nomidrolls, nopostrolls, nooverlays, noskins.

tags Array.<string>

Ooyala Pulse content tags, used to target specific ads.

customParameters object

The Custom parameters to add to the session request. Parameters with names containing invalid characters are omitted. These custom parameters are added to the adserver request URL in the style of "cp.[parameter_name]=[parameter_value]".


RequestSettings

Type:
  • Object
Properties:
Name Type Description
height number

Height in pixels of the video area where ads should be shown.

width number

Width in pixels of the video area where ads should be shown.

maxBitRate number

The maximum bitrate (in kbps) of the media files in the ad response.

linearPlaybackPositions Array.<number>

An Array of numbers which define at what points in time linear ads should be shown.

nonlinearPlaybackPositions Array.<number>

An Array of numbers which define at what points in time non-linear ads should be shown.

insertionPointFilter OO.Pulse.InsertionPointType

If not set, the request is for every kind of insertion point. If set, only the types provided are requested.

referrerUrl string

Overrides the HTTP header's referrer property.

pulse_preview string

Ad ID of the ad the player should display for preview purposes (No tracking will be done).

NOTE! Using this will cause the player to ignore all the other request settings to display the desired ad.

linearSlotSize number

Overrides the number of linear ads per slot.

NOTE! Using this affects the predictability of the Ooyala Pulse forecast functionality. Use with caution.

maxLinearBreakDuration number

The maximum duration in seconds of linear ad breaks.

enforceCacheBusting bool

If set to false, a randomized cache busting parameter is not added to VAST 2.0 tracking URLs which are missing the [CACHEBUSTING] macro. If not set, or set to true (default), the parameter is added.

useVASTSkipOffset bool

If set to true, skip offset information provided in third party VAST tickets determines the skip behaviour of third party ads. If not set, or set to false (default), the insertion policy configured in Pulse determines the skip behaviour instead.

seekMode OO.Pulse.SeekMode

Determines how the ad session behaves when the viewer seeks past one or more ad breaks. If not provided, it defaults to IGNORE.

preferredMediaFormat OO.Pulse.PreferredMediaFormat

If set, the media file with the preferred media format is ranked at the top of the list of the ad's eligible media files.


UiOptions

UI related options for the ad player.

Type:
  • Object
Properties:
Name Type Argument Default Description
width <optional>
AUTO

The width in pixels or OO.Pulse.AdPlayer.Settings.SCALING.AUTO for automatic scaling of the player

height <optional>
AUTO

The height in pixels or OO.Pulse.AdPlayer.Settings.SCALING.AUTO for automatic scaling of the player

VPAIDViewMode OO.Pulse.AdPlayer.Settings.VPAIDViewMode <optional>
NORMAL

The VPAID ViewMode: "THUMBNAIL", "NORMAL", "FULLSCREEN"

renderingMode OO.Pulse.AdPlayer.Settings.RenderingMode <optional>
HTML5_FIRST

How the ad player should render the ads, meaning, Flash first or HTML5 first