# Out-Stream Player

## Implementation and Setup Guide

_Applies to: HTML5 Web and Mobile_  
_Last Modified on __date_modified___

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](#implementation)
- [Setup properties](#setup)
- [Event Callback](#callback)

<a name="implementation"></a>

### 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](#setup) plus an [event listener for runtime player and ad updates](#callback) 
(setup).

```javascript
<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.

<span class="box box--dark-red-1">_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.
_</span>


#### 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>
```

<a name="setup"></a>

### Setup properties

#### adRequest : <code>String</code>

_Mandatory <sup>*</sup>_. 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 : <code>String</code>

_Mandatory <sup>*</sup>_. __Instead__ of a URL pointing to an AdTag you can provide the entire XML-response directly
inside the configuration.

> _<sup>*</sup> 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 : <code>Boolean</code>

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 : <code>number</code>

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 : <code>number</code>

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

#### maxAdWidth : <code>number</code>

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 : <code>boolean</code>

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 : <code>boolean</code>

Sets whether the player starts automatically when it reached the [visibilityThreshold](#threshold).  
The default is `true`.

<a href="threshold"></a>

#### visibilityThreshold : <code>number</code>

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 : <code>boolean</code>

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 : <code>boolean</code>

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: <code>callback(api, container)</code>

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 : <code>Object</code>

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

For further explanations see
[smartclientcore global setup documentation](https://sdk.smartclip.net/smartclientcore/6.0.1/docs/setup-global-config.html).

**skipOffset : <code>number</code>**

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 : <code>number</code>**

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`.

**desiredMimeTypes : <code>[ &#x27;Array&#x27; ].&lt;string&gt;</code>**

- _Optional_. Declaration of accepted media types (whitelist).
Defaulting to types that the browser eventually is able to play. Types must be compliant with the
 [IANA Media Type standard]

**vastMacros : <code>Object</code>**

VAST macros and their values according to the
[IAB](https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html) definition.

#### layoutSettings : <code>Object</code>

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

**progressBarColor : <code>String</code>**

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 : <code>boolean</code>**

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 : <code>String</code>**

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 : <code>String</code>**

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 : <code>String</code>**

_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 : <code>String</code>**

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 : <code>String</code>**

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.


<a name="callback"></a>

### 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](https://sdk.smartclip.net/smartclientcore/6.0.1/docs/events.html).

----