Video Advertising Suite

Docs

> Documentation-Index > Setup Guide

smartClientCore

Sequential Config

adBreak : AdBreak

Setup for an ad-break that defines the sequence of commercial ads, sponsored ads and separation clips.

Commercial and sponsored ads (variant NORMAL and SPONSORED) are defined by the ad-server VAST manifest.

Separation clips (variant OPENER, CLOSER, BUMPER) are optional. They can be defined by the publisher. Most likely they depend on the upcoming TV show or editorial video.

type : string

Optional. Specifies the desired linearity of the upcoming ad slot. Possible values are smartclientcore.AD_TYPE.LINEAR (the default if omitted) and smartclientcore.AD_TYPE.NON_LINEAR.

tag : [string, [ 'Array' ].<string>]

Mandatory *. Defines the ad-request URL(s) that return 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
  • an Array of URLs, ex. use Waterfalling with unknown ad fill rates, manual multiple ads ad-break setup

response : string.

Mandatory *. Defines a VAST manifest directly as a String.

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

adPlugin.initAdSlot(
    {
        tag: 'https://adserver.com/tag-pre?type=vast3xml'
    }
);
// or...
adPlugin.initAdSlot(
    {
        response: `<VAST version="4.0">
                       <Ad id="example-inline-tag">
                           <InLine>
                               <!-- example code -->
                           </InLine>
                       </Ad>
                   </VAST>`
    }
);

limit : number

Optional and applicable with Waterfalling only. Defines the maximum number of impressions to be delivered from a chain of ad-requests.

All SPONSORED ads are also counted as valid impression. The limit value should be increased accordingly

adPlugin.initAdSlot({
    tag: [
        'https://adserver-1.com/tag-pre?type=vast3xml',
        'https://adserver-2.com/tag-pre?type=vast3xml',
        'https://fallback-adserver.com/tag-pre?type=vast3xml'
    ],
    limit: 2
}).then(adLoaded => {
    console.log('### Loading AdManifest success.');

    if (autoplay) {
        adPlugin.startAdSlot();
    }

}, failedLoading => {
    console.warn('### Loading AdManifest failed', failedLoading);
});

opener : Object

Optional. Applies to NORMAL and SPONSORED ads. Intro video for the upcoming ad break, played before all other ads.

  • progressive : string - Mandatory. An Array of objects to video files, used for progressive download. Multiple progressive files can be used, e.g. .mp4 and .webm files to support as many browsers as possible.

  • forcePlay : Boolean - Optional. Defines whether the separation clip must be delivered with ads or always. Defaulting to false.

Other source properties are currently not supported nor required by the add-on. Future versions of the add-on may include streaming resources.

closer : Object

Optional. Applies to NORMAL and SPONSORED ads. Outro video, played after all other ads.

  • progressive : string - Mandatory. An Array of objects to video files, used for progressive download. Multiple progressive files can be used, e.g. .mp4 and .webm files to support as many browsers as possible.

  • forcePlay : Boolean - Optional. Defines whether the separation clip must be delivered with ads or always. Defaulting to false.

Other source properties are neither supported nor required by the add-on.

bumper : Object

Optional. Applies to NORMAL and SPONSORED ads. Special intro video, played once when switching from commercial to sponsored ads or vice versa. Not served if the ad-server response contains no ads of variant NORMAL or SPONSORED.

  • progressive : string - Mandatory. An Array of objects to video files, used for progressive download. Multiple progressive files can be used, e.g. .mp4 and .webm files to support as many browsers as possible.

  • forcePlay : Boolean - Optional. Defines whether the separation clip must be delivered with ads or always. Defaulting to false.

Other source properties are neither supported nor required by the add-on.

adPlugin.initAdSlot(
    {
        tag: 'https://adserver.com/tag-pre?type=vast3xml',
        opener: {
            progressive: 'https://yourpage.com/assets/opener-pre.mp4'
        },
        closer: {
            progressive: 'https://yourpage.com/assets/closer-pre.mp4'
        },
        bumper: {
            progressive: 'https://yourpage.com/assets/bumper-pre.mp4'
        }
    }
);

Example setup to play a static "Station Bumper"

adPlugin.initAdSlot(
    {
        opener: {
            progressive: 'https://yourpage.com/assets/station-bumper.mp4',
            forcePlay: true
        }
    }
);

environmentVars : EnvironmentVars

Used for passing implementation-specific runtime variables.

adContainer : HTMLElement - Recommended with AdBreak.type = smartclientcore.AD_TYPE.NON_LINEAR The DOM element that can be used to deliver non-video creative files. The size and position should be aligned with the video player and should not prevent the user from interacting with the video playback controls.

If omitted, the plugin tries to add a blank DIV element in front of the video element as a fallback.

desiredBitrate : number - Optional. Indicates the desired bitrate in kilobits per second (kbps). The player uses this information to select media files with an appropriate bitrate. Defaulting to 1000.

desiredMimeTypes : [ 'Array' ].<string> - 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
Note: If set, this will override the plugin-internal media types.

desiredVPAIDVendors : [ 'Array' ].<string> - Optional. Declaration of accepted VPAID vendors (whitelist). Each specified String has to represent an unique identifier that can be found within the creative media file URL, most likely the domain name. If omitted, the plugin tries to deliver VPAID creatives from each vendor.

deviceType : string - Optional. Can be either mobile, tablet, desktop or tv. Defaulting to null.

deviceScreenSize : Object - Optional. Maximum size we can achieve when entering fullscreen.

  • width : number - Screen width in pixel.
  • height : number - Screen height in pixel.

macro : Object - Recommended. A list of VAST macros to provide details about how and where the upcoming ad-break is shown. Macro names must be compliant with the VAST 4.x Macros, though custom macro names (like future VAST macros too) are working already.

Example to provide additional data about the current environment

adPlugin.initAdSlot(
    {
        tag: 'https://exampl.com?mph=[MEDIAPLAYHEAD]&bp=[BREAKPOSITION]&ref=[PAGEURL]&cb=[CACHEBUSTER]&foo=[CUSTOMMACRO]'
    },{
         macro: {
            'MEDIAPLAYHEAD': '00:05:21.123',
            'BREAKPOSITION': 2,
            'PAGEURL': 'https://www.mydomain.com/article/page',
            'CUSTOMMACRO': 'bar'
        }
     }
);

// Results in the following URL request
// https://exampl.com?mph=00%3A05%3A21.123&bp=2&ref=https%3A%2F%2Fwww.mydomain.com%2Farticle%2Fpage&cb=1234567890&foo=bar

networkReachability : string - Optional. Can be either wwan, wifi or unreachable. Defaulting to null.

prefetchBuffetAds : boolean - Optional. In order to replace invalid ads in a pod of ads instantly at runtime, buffet ads from wrapper responses must be loaded up-front. prefetchBuffetAds determines whether stand-alone ads (buffet) from wrapper tags will be loaded together with the pod of ads or not. Defaulting to false if omitted.

timeouts : Object - Optional. Definition of timeouts that replace global settings for the upcoming ad-break. Take a look at section Global Config timeouts for relevant information.

Example with desiredBitrate. Other variables will be ignored.

adPlugin.initAdSlot(
    {
        // adBreak
    },{
         desiredBitrate: 1000,
         deviceScreenSize: {
             width: 1024,
             height: 768
         }
     }
 );

Example with deviceType and networkReachability, utilized to calculate an appropriat bitrate.

adPlugin.initAdSlot(
    {
        // adBreak
    },{
        deviceType: 'tablet',
        deviceScreenSize: {
            width: 1024,
            height: 768
        },
        networkReachability: 'wifi'
     }
 );