OutStream Player

Docs

Out-Stream Player

Implementation and Setup Guide

Applies to: HTML5 Web and Mobile
Last Modified on 2023-07-31T13:03:57.096Z

The Out-Stream Player is a stand-alone video ad unit, typically shown within text contents such as articles and recipes in a large format player. It will autoplay muted on becoming visible to the user.

It uses the smartclientcore as the underlying video ad SDK to support the IAB video advertising standards VAST, VPAID and VMAP. This also adds complex sequencing capabilities to play Opener, Closer, Bumper and Sponsored Ads. The Out-Stream Player is fully compliant with smartclip's video advertising eco-system and its connected vendor networks.

Table of Contents

Implementation

The Out-Stream Player application is served as the response to an ad-server request. The response includes everything needed to initialize the player within the requesting ad placement on the page and to deliver one or multiple video ads.

The next paragraphs guide through the required steps to design this ad-server response. Most likely this task has to be done by the Ad-Tech team. The publisher is only required to provide some data (through ad-request parameters) about the placement within the page.

Initialize the Out-Stream Player with: outstreamplayer.connect('#insertme').setup(playerConfig, playerListener) The required parameters are the selector to the DOM element that receives the player (connect), the player and smartclientcore configuration plus an event listener for runtime player and ad updates (setup).

<script>
    ...
    outstreamplayer.connect('#insertme').setup(playerConfig, playerListener)
    //                       ---------         ------------  --------------
    //                       Selector          Setup         Listener
    ...
</script>

DOM placeholder

The DOM placeholder is the element that wraps the Out-Stream Player. The element should be empty in the beginning as it gets emptied afterwards. It should have a unique identifier (by id or any other unique selector) to get found by the player.

_If the element ID starts with digits, make sure to use a qualified DOM selector. Although #001-outstream-container would work as a selector to apply CSS styles, the DOM query selector would not find this element. In this case use div[id=001-outstream-container] as a selector instead. _

Simplest configuration

This is a given JS-Object including everything to get the player running.

A minimal Setup, returning just a URL to a VAST4-AdTag, could look like this:

<script>
...
var playerConfig = {
        adRequest: 'https://example.com/vast4inline.xml'
    }
...
</script>

Setup properties

adRequest : String

Mandatory *. Defines the ad-request URL (AdTag) that returns a VAST manifest. Allowed values are:

  • a single URL, ex. ad fill rate is ensured by the ad-server, a multiple ads ad-break is defined by the ad-server

adResponse : String

Mandatory *. Instead of a URL pointing to an AdTag you can provide the entire XML-response directly inside the configuration.

* One of the adRequest or adResponse property is required but both are not supported. If both have been specified, adRequest will get preferred.

var playerConfig = {
        ...
        adResponse: `<?xml version="1.0" encoding="utf-8"?>
                    <VAST version="4.1">
                    ...
                    </VAST>`,
        ...
    }

debug : Boolean

Enables log output to the console. It this will give you runtime information of the underlying ad framework and the player itself. In addition, the log output can be activated at runtime by calling localStorage.setItem ('debug', true);.
Default is false to keep your console clean.

volume : number

Defines the volume between 0 (always muted) and 1.0 (full loudness). The volume is set after unmuting the player.
Default is 1.0

minAdWidth : number

The value is given in pixels. If the visible area is narrower than this size, no ad will be requested.
Default is 280.

maxAdWidth : number

The value is given in pixels. The player will fill the whole width of the element it gets, to have it narrower a different maximum width can be defined in pixels.
Default is 800.

endingScreen : boolean

By default the player will not close, but show the ending screen when an advertisement is complete (last frame of the ad and a replay button, if an advertisement comes with a Companion Ad of type end-card that will be shown). If set to false the player will collapse. Some VPAID creatives can cause issues with ending screen or replay behaviour. Default is true.

autoplay : boolean

Sets whether the player starts automatically when it reached the visibilityThreshold.
The default is true.

visibilityThreshold : number

Defines a percentage between 0 and 100 visibility. The player uses this value to decide:

  • when the player expands and starts playback (player visibility is greater than the value)
  • when to pause the advertisement (player visibility is narrower that the value)
  • when to resume the advertisement (player visibility is greater than the value)

Default is 50.

prefetching : boolean

When turned off the player will only start to request the ad when it's scrolled into the visible area, this will cause visible lagging as the response has to finish loading before the player will open.
The default is true.

startOpen : boolean

Per default the player will start fully expanded, if a valid ad can be played. Setting this option to false will trigger an expand animation instead once the player comes into view.
Default is true.

onCappedCallback: callback(api, container)

During initialization, the Out-Stream Player is hidden. If it can't find a single playable Ad in the AdTag it triggers a given onCappedCallback-function. Otherwise it starts normally.

Default is empty_function (api, error) => {}

coreSetup : Object

Includes the so called globalAdConfig which is given to the smartclientcore.

For further explanations see smartclientcore global setup documentation.

skipOffset : number

Time value in seconds that identifies when skip controls are made available to the end user by default. Advertisers may define a skipoffset value in its VAST tag that has higher priority than the player setting.

In order to enable skipping from the start set the delay to 0, to show the skip button after 5 seconds set it to 5. Setting a general skipOffset is discouraged.
By default the player does not set a general skip offset, so a skip button will only be shown, if an ad has a specific skipOffset attached.

desiredBitrate : number

Value is given in kpbs. You can specify a target bitrate for the creative, higher values will increase video quality but will cost bandwidth.
Default is 700.

vastMacros : Object

VAST macros and their values according to the IAB definition.

layoutSettings : Object

The following properties are used to change the layout and behaviour of the Out-Stream Player:

progressBarColor : String

The ProgressBar, which indicates the progress of the running ads can have 3 different colors:

  1. red (default)
  2. white
  3. purple

Other colors get dismissed and default to the red layout.

useHoverControls : boolean

By default the controls are always displayed. Turning this property on makes the controls fade-in on mouse-over and fade-out after 3 seconds without further activity. Defaulting to false.

controlsPosition : String

The controls (play/pause, mute/unmute, close) can have two different positions:

  1. inside: Controls are always displayed within the player. If the ad response contains a VPAID creative, the controls position automatically changes to outside.
  2. outside: (default) Controls are always displayed outside the player

branding : String

Whether the smartclip-logo should be displayed at the bottom of the player and if so, which color theme should be applied to it.

  1. none: (default) No branding
  2. gray: promotional label in Helvetica regular 12 px, (#666666) / smartclip logo (#E4002B)
  3. white: promotional label in Helvetica regular 12 px (#ffffff) / smartclip logo (#ffffff)
  4. custom: promotional label in Helvetica regular 12 px, (#666666) / Custom logo URL (SVG, PNG)

logo : String

Requires branding = "custom" Target URL to a logo image that should match with the following specification:

  • file format SVG or PNG (with transparency)
  • height of 20px or higher
  • maximum width of 120px

promotionalLabel : String

Defines the text left to the logo. Defaults to an empty text, which then does not get rendered. Maximum characters of 20 are allowed, everything longer gets sliced.

advertisingLabel : String

Defines the text above the player. Defaults to ADVERTISEMENT. Using an empty string "" prevents rendering the label. Maximum characters of 20 are allowed, everything longer gets sliced.

Event Callback

A function that receives all events triggered by the smartclientcore.

var playerListener = function callback(event) {
    console.log('%c Callback::callback() ', 'background: #34495e; color: #ecf0f1; font-weight:bold;', event);
};

For further explanations see smartclientcore event documentation.