Pulse SDK API Documentation

Namespace: Pulse

OO. Pulse

The Pulse SDK.

This class is used to request ad sessions from 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> Live :string

Live parameters used to disable certain tracking, secondary lookup requests, real-time bidding requests, and/or cookie syncing for a live event.

Type:
  • string
Properties:
Name Type Default Description
DISABLE_ALL string disableAll

Turn off all tracking (except for impression and click-through tracking), session lookup requests, location lookup request, and real-time bidding requests.
ALL_TRACKINGS string allTrackings

Turn off everything else except all tracking.
SESSION_LOOKUP string sessionLookup

Turn off everything else except session lookup request.
LOCATION_LOOKUP string locationLookup

Turn off everything else except location lookup request.
REAL_TIME_BIDDING string realTimeBidding

Turn off everything else except real-time bidding requests and their associated cookie syncing.

<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
HLS string application/x-mpegURL
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 Pulse account to use.
deviceContainer string

Pulse device container.
persistentId string

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 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 Pulse.
contentForm OO.Pulse.ContentForm

Content form is used to determine the ad insertion policy.
id string

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

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

This value cannot be negative.
flags Array.<string>

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

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 parameters are added to the adserver request URL in the style of "cp.[parameter_name]=[parameter_value]".
accountCustomParameters object

The Account Custom Parameter(s) to add to the session request. Parameter names and values containing invalid characters will be omitted. These parameters are added to the adserver request URL in the style of "acp.[parameter_name]=[parameter_value]". NOTE: The account custom parameter values cannot contain any spaces or any of the following characters: comma (,), semicolon (;), double quote/quotation mark ("), single quote/apostrophe ('), backslash (), pipe (|), tilde (~), or ampersand (&).

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 Array.<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.
enableGdpr bool

Set to true if the ad request is subject to GDPR regulations. See Implementation Guidelines for more information.
enableViewability bool

Set to true if the Pulse SDK should also track the viewability and handle viewport related events (focus/blur, resizes etc.) according to ensure correct measurements
viewabilityBenchmark object

Viewability benchmark (syntax sample: [60,3]) specifying the basis of assessment for the viewability measurement performed by the Pulse SDK. Default value is [50,2].
gdprConsentString string

Pass in the user's URL safe and base64 encoded consent string related to GDPR regulations, which may be obtained through the Consent Management Provider (CMP) JS API. This string is built up according to the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe. The data structure specification can be found at Consent string and vendor list formats v2 Final. For more information on the API, refer to CMP JS API v1.1 Final.
gdprPersonalDataIncluded bool

Set to true if you are passing in personal information when creating the ad request to Pulse. One of the location where it is possible to pass in personal information is in the customParameters of OO.Pulse.ContentMetadata.
startAdTimeout number

Overrides The maximum amount of time the player or integration should wait for the ad to start playback before reporting inventory.
thirdPartyTimeout number

Overrides The maximum amount of time the player or integration should wait to unwrap and load a third party ad before reporting inventory.
totalPassbackTimeout number

Overrides The maximum amount of time the passback player should wait to find a working ad in the passback chain before moving to the last ad in the chain or reporting inventory.
breakNumber number

Overrides the break number detected in Pulse in order to request ads for a specific ad break.

DEPRECATED! breakNumber has been deprecated. Use midrollBreakNumber to request ads for specifc midroll ad break.
midrollBreakNumber number

Overrides the midroll break number detected in Pulse in order to request ads for a specific midroll ad break.
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 Pulse forecast functionality. Use with caution.
maxLinearBreakDuration number

The maximum duration in seconds of linear ad breaks.
minLinearBreakDuration number

The minimum 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.
disableMediaFileFiltering bool

If set to true, media files will not be filtered out based on maxBitRate and browser compatibility.
rtbPid string

Real-time bidding (RTB) persistent ID (PID) anonymizes the standard PID and, if set, will be sent in bid requests to Demand Side Platforms instead of the standard PID, to ensure the privacy of your end users' information when using Pulse Programmatic (SSP).
rtbDcid string

RTB Device Container ID overrides the RTB device type detected in INVIDI Pulse, in order to request ads for a specific RTB device type. You must provide a valid value for one of the available device types as specified in the OpenRTB API Specification. For more information, see INVIDI Pulse SDK parameter reference.
liveParameters Array.<string>

A list of live parameters indicating which behaviours should be disabled for a live event. If an empty list is set, the behaviour defaults to DISABLE_ALL.

NOTE!Notice that if all parameters are sent at once, then no action would be taken, i.e DISABLE_ALL would disable everything and other parameters would re-enable them.

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