Outstream Player Implementation Guide

Aniview™ disruptive and proprietary technology allows Advertisers to offer mobile video ads quickly & easily with a single HTML tag across the entire publisher's mobile platforms.

Aniview player is a Javascript player that works with the Aniview ad server to play ads.

1 Player Element
2 Player Configuration
3 Player Javascript
4 Player Instantiating
5 Putting it all together
6 adConfig Configuration Options
7 Player API
- 7.1 new avPlayer(adConfig)
- 7.2 play()
- 7.3 mute()
- 7.4 unmute()
- 7.5 pause()
- 7.6 resume()
- 7.7 startAd()
- 7.8 close()
- 7.9 updateGui(config)
- 7.10 resize(width, height)
- 7.11 getAdDuration()
- 7.12 getAdRemainingTime()
- 7.13 getAdVolume()
- 7.14 setAdVolume(vol)
- 7.15 getAdCompanions()
- 7.16 getWidth()
- 7.17 getHeight()
- 7.18 on(evt, func, context)
- 7.19 off(evt, func)
- 7.20 startViewability(elid, callback, ratio)
- 7.21 stopViewability()
- 7.22 getViewability()
- 7.23 getContentPaused()
- 7.24 getContentCurrentTime()
- 7.25 pauseContent()
- 7.26 resumeContent()
- 7.27 setContentVolume(vol)
- 7.28 pausePlayer()
- 7.29 ResumePlayer()
- 7.30 getReadyAds()
- 7.31 setWaterfallState(state, force)
- 7.32 startTemplate(aniBox)
- 7.33 setAdConfig({atribute:value})
- 7.34 startFloat({attribute:value})
- 7.35 stopFloat()
8 Player Events
9 Sample Events
- 9.1 Player Initialized Event
- 9.2 Impression Event
- 9.3 Identify when the Player Finished Calls
10 Player Templates
- 10.1 Template Position Wrapper
- 10.2 Starting Template
11 Templates Configuration
12 User Id Modules
13 Prebid ortb info
14 Related articles

Player Element

The player is created on an element id specified by adConfig.position

<div id="aniplayer"></div>

Player Configuration

The configuration of the player is an object with some configuration properties that instruct the player on how to function.

For example:

var adConfig = {
    publisherId:      '[Publisher_ID]',
    channelId:        '[Channel_ID]', 
    ref1:             '',
    width:            300,
    height:           250,
    autoPlay:         true,
    loop:             true,
    vastRetry:        3,
    errorLimit:       5,
    soundButton:      true,
    pauseButton:      true,
    preloader: {
      type:           '',
      link :          '',
      clickthrough:   '',
    },
    midrolltime:      2,     
    position :        'aniplayer'
  };

Player Javascript

The player code is located at https://player.aniview.com/script/6.1/aniview.js

Player Instantiating

myPlayer= new avPlayer(adConfig);
myPlayer.play();

Putting it all together

adConfig Configuration Options

Name	Mandatory	Default Value	Values	Description
publisherId	Yes		String	Aniview publisher id
channelId	Yes		String	Aniview channel id from the same account of the publisher id used
position	Yes		String	the div id where the player should be created
loop	No	false	Boolean	loop is used to control looping of video preloader true: At the end of content video, continue looping false: No content loop To control ad loops, use maxrun or maximp
width	yes		Number	The player width in pixels If width = 100 and height = 0, width is auto detected based on containing element
height	yes		Number	The player height in pixels If width = 100 and height = 0, height is auto detected based on containing element and is calculated as width / 1.777
minHeight	No		Number	Minimum player height - Used with width/height of 100/0
minWidth	No		Number	Minimum player width - Used with width/height of 100/0
maxRun	No		Number	Maximum number of waterfall runs in the player session
maxImp	No		Number	Maximum number of impressions per player session
vastRetry	No		Number	Number of consecutive waterfall retries without delay so the number of runs is 1 + vastRetry
errorLimit	No		Number	Maximum number of (1 + vastRetry) runs of the waterfall that do not generate impression. This means (1 + vastRetry) * (1 + errorLimit) - max number of consecutive waterfall runs that do not generate impression If there is an impression the counter reset to 0
format	No	“all”	String with “js”, “html5“	Choose a format to play, If “html5” than vpaids will not run in the player
autoplay	No	true	Boolean	Defines if calling startAd automatically. If false, startAd should be called after getting onLoad callback event. With the ShortTag template this is managed automatically in order to play the ad when in view.
ref1	No		String	Macro list ref1: “AV_MACRO1=value1&AV_MACRO2=value2“ Values should be URL encoded
preloader				Used to display content while the player is searching for ads
type	No		String	“Content” : video preloader “Image“ : Image “js“ : Javascript that runs in an iframe
link			String Array Object	Link to resource url If preloader type is Content, can also be an array of videos If preloader is type js, it can be an object defining the iframe to run - similar to the options in passbackUrl
clickthrough			String Array	Clickthrough url when clicking on the content. Not relevant in js If preloader is Content, can also be an array of clickthrough urls per video in the content array
poster			String	If preloader type is Content, url of an image to display while content is loading
autoplay			String	If preloader type is Content, indicate if to start the content video automatically or its click to play
midrolltime	No	0	Number	Number of seconds to wait between each (1 + vastRetry) waterfall runs
midrolldelay	No	0	Number	Number of seconds to wait before running the waterfall the first time
startaddelay	No	Auto calculated	Number	Number of seconds to wait for higher priority ad source to return with AdLoaded before calling startAd to the highest priority ad source that already responded with AdLoaded
startmidroll	No	0	Number	Delay in seconds to wait before calling startAd after the end of an impression. This will create a minimal delay between ad videos
startdelay	No	0	Number	Delay in seconds of calling startAd the first time
midrollfunc	No	null	function	If midrollfunc is defined, it is called before running the waterfall every time. its parameter is a callback function to call and will continue the operation Its a way to control the calls to the waterfall in a very granular way
soundbutton	No	true	Boolean	Show or not show the sound button
pausebutton	No	true	Boolean	Show or not the pause/play button
closebutton	No	true	Boolean	Show or not the close button
Skip	No	false	Boolean	Show or not the skip button
skipTimer	No		Number	Time to wait before showing the skip button. Required to be > 0 for skip button functionality
skipText	No		String	Text to show in skip button
skipStyle	No		Object
position			string	skipStyle.position = “inside“ will show the skip timer inside the skip button
closeevent	No	false	Boolean	If true, when clicking the close x button, the player is not closed and AdClosed event is fired. Its the responsibility of the wrapping code to close the player with the close() api
passbackUrl	No		string	Link to a javascript that will execute in an iframe and will be displayed after the player finishes all its retries and impressions, contact support for the exact format It can also be an object as defined below
reqOnView	No		Boolean	If true, play calls ad sources only when in view
startAdOnView	No		Boolean	If true, calls to startAd will be done only when the player is in view
startAdOnViewPerc	No		Number	Viewability % used for startAdOnView. Default is 50
reqOnViewTopDist	No		Number	Player will send requests only if the distance of the top of the player to the bottom of the viewport is below reqOnViewTopDist pixels Requires reqOnView: true
passbackUrl	No		object
url	No		String	Link to javascript to write into the iframe. passback tags can be used as is without any special formatting
width	No	100%	Number	width of passback iframe iframe is centered
height	No	100%	Number	height of passback iframe iframe is centered
color	No	“#000“	String	background color
passbackpriority	No	false	Boolean	If true, passback will be used also if preloader is defined
hideControls	No	false	Boolean	Hide player controls or not
logo	No	true	Boolean	If false, does not show the player logo
customLogo				Enable showing a custom logo
link			String	Link to logo image
height			Number	height in pixels of the logo
width			Number	width in pixels of the logo
text			String	Text to display near the logo, for example, “Ads by“
top			Number	Amount of pixels from the top to show the logo
clickthrough			String	Url to open when clicking on logo
waitforconsent	No	true	Boolean	If true, player will open only after receiving consent
maxp	No	5	Number	Max concurrent calls to vpaid initAd
autosounddetect	No	False	Boolean	If autosounddetect is true, the ads player will try to start ads with volume on. If its not supported ads will start muted. (Not supported on IOS)
autosoundvolume	No		Number	Volume set up, between 0-1
imarpm	No		Number	Limit max requests per minute for all IMA ad sources in the waterfall
vastIconEnabled	No		Boolean	If true, if a vast includes an icon definition, the icon will be displayed on one of the ad corners
adscontrolpositioning	No	'right'	String	Moves the volume and fullscreen icons away from the right side. This config can be use to avoid conflict with google IMA skip button

Player API

new avPlayer(adConfig)

Instantiate the player object with the adConfig configuration

play()

Start the player instance. Should be called only once

mute()

Mute the audio of the currently playing video

unmute()

Unmute the current playing video

Must be called as a result of user click action in the page

pause()

Pause the currently playing video

resume()

Resume the player if it’s paused

startAd()

Should be used only with autoPlay: false

After getting the AdLoaded event, can be used in order to call startAd to the ad. The player will automatically continue after that to call the next ads

close()

Close the player and stop its functionality

updateGui(config)

Can be used to set specific gui options

config is an object that can include one or more configurations. Possible settings:

close: true/false
show or hide the close button
skip: true/false
Show or hide the skip button
playPause: true/false
Show or hide the play/pause button
sound: true/false
Show or hide the sound button
logo: true/false
Show or hide the player logo

resize(width, height)

Resize the player to the requested width and height

getAdDuration()

Returns the current ad duration in seconds

getAdRemainingTime()

Returns the number of seconds remaining till the end of the current playing ad

getAdVolume()

Returns the volume of the current playing ad

setAdVolume(vol)

Set the current ad volume

getAdCompanions()

Returns the ad companions string of the current playing ads from the vast response

getWidth()

Returns the player width in pixels

getHeight()

Returns the player height in pixels

on(evt, func, context)

Register an event listener for player events

off(evt, func)

Unregister an event/function

startViewability(elid, callback, ratio)

Start viewability monitoring in the player

Parameters:

elid: The element to measure, by default will use the player position
callback: Callback function to call on every viewability change. Callback function parameters:
- Boolean: in view or not
- Number: Current ratio of viewability
- String: State that indicates if below/above/partial the fold
Viewability ratio defined as viewable. Default is 0.5

stopViewability()

Stop viewability monitoring

getViewability()

Returns current viewability of the player

getContentPaused()

Returns a boolean to indicate if the content video is playing or not

getContentCurrentTime()

Returns the content video current time

pauseContent()

Pause the currently playing video content

resumeContent()

Resume playing of the video content

setContentVolume(vol)

Set the volume of the content

pausePlayer()

Pause calls to startAd

ResumePlayer()

Resume calls to startAd

getReadyAds()

Returns the number of ready ads (Ads in AdLoaded state)

setWaterfallState(state, force)

Pause or resume additional calls to startAd.

state	force	description

state	force	description
true	true	Resume calls to startAd. If there is a loaded event call startAd
true	false	Do not use
false	false	Pause calls to startAd. Do not stop currently running call to startAd if there is any
false	true	Pause calls to startAd. If there is an active call to startAd that did not respond yet, kill it.

startTemplate(aniBox)

Start player template implementation. See below for details on template configuration

setAdConfig({atribute:value})

Update the player config

startFloat({attribute:value})

Start or restart the floating using an alternate floating object, for example:

startFloat({"closeButton":true,"floatOnBottom":true,"position":"Bottom-Right","size":0.7,"bottom":5,"right":5,"resize":true})

stopFloat()

Stop the floating

Player Events

The player on() function can be used to subscribe to events. Multiple listeners can be set for each event

In addition, callback on functions are supported to the events

Note: With vpaid ad sources, the player relies on events triggered by the vpaid. In some cases, some events are not supported by vpaids so those events might not be called sometimes.

The supported events are:

Event name	Description

Event name	Description
AdLoaded onLoad	Indicates the first time an ad sources triggered the AdLoaded event
AdReady	Fires on every ad AdLoaded event of any ad
AdEvent onEvent	Granular vast and request bid events per ad source request bid error (no bid) all other vast events such as pause, resume, etc… vpaid progress events: initAd initAdError initAdTimeout AdLoaded startAd startAdTimeout startAdError
AdImpression onPlay	Called when there is a video impression. The AdImpression event pass a parameter with extra data that is used for 3rd party reporting:
AdVideoFirstQuartile onPlay25	Called when the ad reached 25% of the ad video
AdVideoMidpoint onPlay50	Called when the ad reached 50% of the ad video
AdVideoThirdQuartile onPlay75	Called when the ad reached 75% of the ad video
AdVideoComplete onPlay100	Called when the ad completed
AdClickThru onClick	Called when the ad is clicked on
AdPaused onPause	Called when the ad is paused
AdPlaying onResume	Called when the ad starts playing or resumed
AdError onError	Called by the player every time it finish running 1 + vastRetry waterfall runs without impression Called also whenever the player decides that it should stop running, for example when maxImp or maxRun is reached, in this case the event will pass a parameter: {errorlimit: true} to indicate the player is stopping calls for ads
AdStopped onStopped	Called when the player is stopping
AdSkipped onSkip	Called when an ad is skipped
AdClosed onClose	Called when the player is closing
AdVolumeChange onUnmute onMute	Called when the ad volume is changed
ContentImpression onContentPlay	Called whenever a content video is starting to play
ContentComplete onContentPlay100	Called whenever the content video is ending
ContentPaused onContentPaused	Called when the content video is paused
ContentPlaying onContentPlaying	Called when the content video resume playing
ContentClick onContentClick	Called when the content video is clicked
Inventory onInventory	Called when the player is initialized
InventoryRequest onInventoryRequest	Called every time the player starts a waterfall run
AdViewableImpression	Called on viewable impression event - when ad is viewable for at least 2 consecutive sconds

Sample Events

Player Initialized Event

The player is initialized on the inventory event

Impression Event

Identify when the Player Finished Calls

An AdError event is called every time a set of vastRetry+1 calls to the waterfall finished without impression or when at least one limit of the player configuration is reached (maxRun, maxImp, errorLimit)

When the player finished calls and will not continue anymore, it calls AdError event and passes an errorlimit parameter

The player also provides the reason for stopping in reason field

Possible values are:

Player mode:

errorlimit: Player reached max number of waterfall runs without impression
emptywf: The waterfall is empty
maxrun: The player reached adConfig.maxrun waterfall runs
maximp: The player reached adConfig.maximp impressions

Vpaid mode:

maxpagereq: The vpaid reached the maximum number of ad requests on the page and cannot run again
maxpagerun: The vpaid reached the maximum number of runs on the page

Player Templates

The player support advanced templates such as In Article, Floating, Sticky and many customizations.

Aniview provides a tool for managing templates configuration. this section describes the configuration flags available for templates configuration

In order to activate the template, its is required to wrap the player element in additional elements and call the startTemplate API passing the element of the parent of the player position element

Template Position Wrapper

The player position (<div id="aniplayer_aniviewJS562811134">) is wrapped with an aniBox div and another wrapper

The player template generator automatically build this structure

The player is created inside the position div with a unique id

Starting Template

In order to start running a template with the below configuration options, it is required to call startTemplate passing the element of the parent of the position passed in position. In this case it will be the aniBox element

Templates Configuration

The templates configuration ads additional configurations to adConfig

Those configurations are used only if startTemplate is called

Name	Mandatory	Default Value	Values	Description

Name	Mandatory	Default Value	Values	Description
playOnView		false	Boolean	If set to true, the player will automatically check viewability and will call startAd only when in view.
startOnView		false	Boolean	If set to true, the player will start only when in view. This means that inventory will be sent only when in view and the player loads
reqOnView		false	Boolean	If set to true, the player will run the waterfall and call ad sources only when in view. When out of view, when its time to call the ad sources, the player will verify that its in view and if not it will wait till the player is in view
vitab		false	Boolean	If set to true, tab viewability is taken into account when checking viewability
pauseOnUnseen		false	Boolean	If set to true, the player will pause when its out of view
pauseOnBlur		false	Boolean	Pause when browser window lose focus
openAnim		false	Boolean	If true, player opens in animation
hideInitPreloader		false	Boolean	Hide player when searching for ads
showPlayer			Boolean	Force showing the player
scriptId	Yes		String	Id of script used to position the player if no pos defined
posId			String	Position id If defined the player will be located on the element with the specified id
posTag			String	Position tag If defined the player will be located on the element with the specified tag name
posClass			String	Position class If defined the player will be located on the first element with the specified class
posSelector			String	Position selector If defined, the player position will use querySelector with the given string
posDfp1x1			Boolean	If defined, it is assumed the player script is served inside a 1x1 hidden iframe generated by DFP The player will position at the place of the iframe in the parent window
adLabel			Object	If defined, it will appear above the player e.g. {"text":"Advertisment"}
pricegranularity			“high” ”medium” ”low” or a number	high (0.01): $0.01 jumps medium (0.1): $0.1 low (1): $1 Or can be a number. for example, 0.2 means 0,0, 0.2, 0.4, etc $0.2 jumps
pricegranularitymax			Number	max $ value. Higher number will translate to this value
pricegranularitydecimals			Number	Number of decimals after the . Undefined is auto - based on granularity
Player types
InArticle/InFeed				The player opens up only when there is an ad impression and takes the place in the page to display the ad. When it finish usually it collapse Use with a combination of playOnView and other flags
Floating			Object	A floating player has a position in the page body and when out of view it floats to a fixed position over the page is its always viewable A floating player can start as InArticle/InFeed and float when the position is out of view
size			Number 0-1	The size of the floating player will be the size of the original player x size
right			Number	Create a margin of the defined number from the right side of the window
bottom			Number	Create a margin of the defined number from the bottom of the window
customCss			String	Used to define custom CSS that will be implemented in <style></style>. Note it is appended to all existing CSS
floatingCss			String	Used to define custom place for the floating player, for example use the below for a bottom-left floating half the size of the original player. Note it overwrites/replaces the floating’s original CSS. For example: `'z-index:10000001;position:fixed; bottom:5px; left:5px; -webkit-transform:scale(0.5); -webkit-transform-origin:bottom left; transform:scale(0.5); transform-origin:bottom left'`
floatOnBottom			Boolean	By default the floating player only appears when scrolling down, If true, will float whenever the player is out of view
closeButton			Boolean	If true, show a close button that will unfloat the player to its original position
Sticky			Object	A sticky player is always sticking i a fixed position on the screen, typically in one of the screen corners
size			Number	The size of the sticky player will be the size of the original placement x size Set to 1 for easy configuration
position			String	Defines the position of the sticky player. Can be one of: Bottom-Right Bottom-Left Top-Right Top-Left
right			Number	Create a margin of the defined number from the right side of the window
left			Number	Create a margin of the defined number from the left side of the window
top			Number	Create a margin of the defined number from the top side of the window
bottom			Number	Create a margin of the defined number from the bottom side of the window

User Id Modules

User id modules are addon modules, most available as part of prebid, that provide addition user id info to bidders. it is possible to setup those providers on the manage.aniview.com settings or in adConfig.

user id modules configuration is under adConfig.uidproviders.idName = { Prebid configuration params }

Aniview is using the default storge configuration for each module

The params can be used as below but can also include additional info such as hashed email if available, please contact the id provider rep for more info

Module	adConfig parameters

Module	adConfig parameters
ID5	"id5Id": { "partner": "id provided" }
pub common	"pubCommonId": { "enabled": "1" },
Hardon	"hadronId": { "partnerId": "id provided" },
33Across	"33Across": { "pid": "id provided" },
Identity link	"identityLink": { "pid": "id provided" },
Criteo id	"criteoId": { "enabled": "1" },
Unified id	"unifiedId": { "partner": "id provided" },
Panorama id	"panoramaId": { "clientId": "id provided" },
UID2	Contact tradedesk for info	Requires hashed id
Live Intent	Contact id provider	Requires hashed id
connectId	Contact id provider	Requires hashed id
Intent Iq

Example configuration:

Prebid ortb info

OpenRTB site info can be set in

adConfig.openrtb.site = {

…ortb site info…

}

In any case, the player will automatically pass the page and domain

OpenRTB content info is automatically taken from the content player config.content.contents[] array

OpenRTB content and ext can be set in this object

Some ssps and content providers support IrisTV. For support using Aniview CMS please contact your account rep

Iris data can be set in:

config.content.contents[0].irisId

config.content.contents[0].irisContext