smartClientCore - Setup

Table of contents

• Global Config
• Sequential Config

Global Config

• debug
• blockInsecureURL
• maxWrapperDepth
• adReinsertion
  • HOMAD
• adVerification
  • OMID
  • nonOMID
• skipOffset
• timeouts
  • adRequest
  • adRequestChain
  • adSlotRequest
  • videoRequest
  • vpaidRequest
  • vpaidReadiness

debug : Boolean

Enables log output to the console.

blockInsecureURL : Boolean

By default insecure URL requests (tags, tracker, media files) will not be executed within secure environment. Default is true.

maxWrapperDepth : number

When serving an ad involves a chain of wrappers, an infinite loop is possible where a chain of Wrappers never results in a final inline VAST response. In general, wrappers should be limited to ten before resulting in an inline response. If the add-on detects more than ten wrappers, the add-on rejects any subsequent responses in the chain and returns VAST error 302. Default limit is 10 wrappers.

adReinsertion : Object

homad : Object

The add-on has been extended with the HOMAD HTML5 solution to help bypassing ad-blockers. All ad-related resources (tags, creative files, trackers) will be redirected to HOMAD once they get blocked for any reason.

enabled : Boolean - Enables HOMAD ad-reinsertion. Disabled by default.

setup : Object - HOMAD configuration

If the activationCallback is omitted or does not respond within 250 milliseconds, HOMAD will be automatically activated (if enabled before).

let globalAdConfig = smartclientcore.SCHEMA.create(smartclientcore.SCHEMA.GLOBAL_CONFIG);
globalAdConfig.adReinsertion = {
    homad: {
        enabled: true,
        setup: {
            globalConfig: 'https://s3.amazonaws.com/homad-global-configs.schneevonmorgen.com/global_config.json',
            clientConfig: 'https://test.s3.amazonaws.com/homad/homadConfigTestHttps.json',
            enableSessionCoverage: true,
            activationCallback: (reason) => {
                return new Promise((resolve, reject) => {

                    // The reason for activating HOMAD sounds reasonable?
                    resolve();

                    // otherwise
                    //reject();
                });
            }
        }
    }
};

adVerification : Object

OMID : Object

Ad-verification vendors that rely on the Open Measurement Interface Definition API (OMID) are enabled by default. The following properties may be adjusted to enable selected verification vendors only and to limit the measurement session execution time.

More information on OMID and OM SDK available at: https://www.iab.com/omsdk

vendorWhitelist : [ 'Array' ].<string> - List of accepted AdVerification vendors (whitelist). Each specified String has to represent an unique identifier that can be found within the verification code resource URI, most likely the domain name.

If omitted, the add-on tries to load verification code from each vendor.

sessionCleanupDelay : number - Time value in seconds that specifies a delay for closing the current measurement session after the ad has finished playback. Default is 3 seconds.

The verification code should have sufficient time to ensure any measurement and reporting is completed before cleaning up, in order to minimize discrepancies.

timeoutScriptLoad : number - Representing the number of seconds a OMID vendor can take to load and initialize its code before being terminated. Defaulting to 0.5 seconds if omitted.

playerHandles : Boolean - Whether the player takes responsibility for Open Measurement, e.g. native implementations of OMID. Defaulting to false if omitted.

nonOMID : Object

Ad-verification vendors that base or rely on proprietary measurement and reporting logic.

meetrics : Boolean - Disabled by default. Enables Meetrics viewability measurement for video advertisment with any VAST and VPAID creative.

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 publisher setting.

timeouts : Object

let globalAdConfig = smartclientcore.SCHEMA.create(smartclientcore.SCHEMA.GLOBAL_CONFIG);
globalAdConfig.timeouts = {
    adRequest: 1,
    adRequestChain: 2,
    adSlotRequest: 4,
    videoRequest: 3,
    vpaidRequest: 1,
    vpaidReadiness: 3,
};

adRequest : number

The number of seconds a single ad request can take to load before being terminated.
Default is 1 seconds.

adRequestChain : number

The total number of seconds a single ad request chain (VAST Wrappers and final VAST Inline tag) can take to load before being terminated.
Default is 2 seconds.

adSlotRequest : number

The total number of seconds an ad-slot request (from calling initAdSlot until the Promise resolves or rejects) can take before being terminated.
Default is 4 seconds.

videoRequest : number

Representing the number of seconds a video creative can take to load before being terminated.
Default is 3 seconds.

vpaidRequest : number

Representing the number of seconds a VPAID creative (JavaScript resource) can take to load before being terminated.
Default is 1 seconds.

vpaidReadiness : number

Representing the number of seconds a VPAID creative can take to initialize and respond (from calling VPAID.initAd() until the creative triggers the AdLoaded event) before being terminated.
Default is 3 seconds.

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 (type NORMAL and SPONSORED) are defined by the ad-server VAST manifest.

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

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'
        }
    }
);

environmentVars : EnvironmentVars

Used for passing implementation-specific runtime variables.

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 null. Note: If set, this will disable the plugin-internal bitrate detection.

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. For a list of supported media types see tbd - Glossar 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.

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) will be loaded together with the pod of ads or not. Defaulting to false if omitted.

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'
     }
 );