Placements are entities representing “real-estate spaces” on screen, i.e. HTML elements into which we render ads. Placement entities connect channels to custom placements on any site utilizing CSS selectors and allow customization of the placement’s behavior when showing AniView Aniview instream or outstream players.
| Table of Contents |
|---|
Placement Element
The player is created on an element id specified by placementConfig.position:
| Code Block | ||
|---|---|---|
| ||
<div id="aniplayer"></div> |
Placement Configuration
The configuration of the placement is a configuration object with properties that instruct the placement on how to handle the placement element and render the correct ad.
...
| Code Block | ||
|---|---|---|
| ||
var placementConfig = {
publisherId: '[Publisher_ID]',
channelId: '[Channel_ID]',
ref1: '',
width: 300,
height: 250,
errorLimit: 5,
position : 'aniplayer'
}; |
Placement Javascript
The player code is located at https://player.aniview.com/script/webm/aniview-displayads.js
Placement Instantiation
| Code Block | ||
|---|---|---|
| ||
myPlacement = new avDisplay(placementConfig);
myPlacement.play(); |
Putting it all together
| Code Block | ||
|---|---|---|
| ||
<div id="aniplayer"></div>
<script type="text/javascript" id="aniviewJS">
(function()
{
var myPlacement;
var placementConfig = {
publisherId: '[Publisher_ID]',
channelId: '[Channel_ID]',
ref1: '',
width: 300,
height: 250,
errorLimit: 5,
position : 'aniplayer'
};
(new Image).src = "https://track1.aniview.com/track?pid="+placementConfig.publisherId+"&cid="+placementConfig.channelId+"&e=playerLoaded"+"&cb="+Date.now();
var placementUrl = 'https://player.aniview.com/script/webm/aniview-displayads.js'+'?v=1&type=s&pid='+placementConfig.publisherId;
function downloadScript(src,adData) {
var scp = document.createElement('script');
scp.src = src;
scp.onload = function() {
myPlacement = new avDisplay(placementConfig);
myPlacement.play();
};
document.getElementsByTagName('head')[0].appendChild(scp);
};
downloadScript(placementUrl,placementConfig);
})();
</script> |
placementConfig 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 | |
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 |
creativeDimensions | No | [{ w: 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
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
ref1
No
String
Macro list
ref1: “AV_MACRO1=value1&AV_MACRO2=value2“
Values should be URL encoded
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
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
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
passbackUrl
No
object
width
No
100%
Number
width of passback iframe
iframe is centered
height
No
100%
Number
height of passback iframe
iframe is centered
hideControls
No
false
Boolean
Hide player controls or not
Placement API
avDisplay(placementConfig)
Instantiate the placement object with the placementConfig configuration
play()
Start the player instance. Should be called only once
pause()
Pause the currently playing video
resume()
Resume the player if it’s paused
close()
Close the player and stop its functionality
resize(width, height)
Resize the player to the requested width and height
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
getReadyAds()
Returns the number of ready ads (Ads in AdLoaded state)
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
...
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
...
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:
| Code Block |
|---|
{
"asid": "Ad source id",
"clickThrough": "Ad click url if available",
"videoUrl": "Url of media file if available",
"mt": "Media type, vast or vpaid",
"tagInfo" : {
"url": "Actual ad source meta data, template of url",
"bidCpm": Actual bid cpm (prebid, rtb) or floor if vast/platform link,
"pubCpm": Publisher CPM after rev share,
"floorCpm": floor price used
"bidCode": "Bidder code from prebid",
"vast": Array of vast chain
}
} |
...
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
| Code Block | ||
|---|---|---|
| ||
player.on("Inventory", function(){
//Player is initialized
}); |
Impression Event
| Code Block | ||
|---|---|---|
| ||
player.on("AdImpression", function(){
//Ad impression accoured
}); |
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
| Code Block | ||
|---|---|---|
| ||
player.on("AdError", function(res){
if(res && res.errorlimit) {
//Player stopped
}
}); |
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
| Code Block | ||
|---|---|---|
| ||
<div style="width: 100%; margin: 0px auto; max-width: 640px;">
<div id="aniBox" style="height: 1px;">
<div id="aniplayer_aniviewJS562811134">
</div>
</div>
</div> |
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
| Code Block |
|---|
player.startTemplate(document.getElementById(placementConfig.position).parentNode) |
Templates Configuration
The templates configuration ads additional configurations to placementConfig
Those configurations are used only if startTemplate is called
...
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"}
...
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
Placements extend the regular studio tag configurations in the following fashion:
The following properties from the Studio Tag are ignored by Placements:
playOnView - playing or not depends on the type of creative to render, so for video creatives this config will be passed in separately.
fullscreen- placements are creative-neutralpauseButton - assumes pause-able media, not creative neutral
soundButton - assumes media has sound, not creative neutral
showbigplay - assumes play-able media, not creative neutral
autovolume - assumes media has sound, not creative neutral
imaiosskip- assumes IMA is involved, video centric, not creative neutral
autoPlay- assumes media is playable, not creative neutral
replayFunc - assumes media is playable, not creative neutral
ifrhandler- assumes media requires an iframe handler, not creative neutral
startaddelay- assumes media is playable, not creative neutralstartmidroll- assumes media is playable, not creative neutral
backgroundColor- assumes media has background, not creative neutral
nativetest - assumes media is a tested native video, not creative neutral
nativevideo - assumes media is a native video, not creative neutral
autosound - assumes media has sound, not creative neutral
closeButtonStyle - assumes media is close-able, not creative neutral
closeButton - assumes media is close-able, not creative neutral
timelinechange - assumes media has timeline dependent position, not creative neutral
noifsnd- assumed media has sound, not creative neutralskipText- placements have their own skip implementationvastRetry- assumes media is VAST, not creative neutralmode- setting for VAST, not creative neutralloopVideo- assumes media is a video, not creative neutralMidrolltime - assumes media is a video, not creative neutral
loop - assumes media is a video, not creative neutral
loopVideo - assumes media is a video, not creative neutral
timelineMode - assumes media has a timeline, not creative neutralvastIconEnabled - assumes media is a video, not creative neutrallastFrame - assumes media is a video, not creative neutral
The following properties from the Studio Tag haven’t yet been implemented by Placements:
...
adLabel
...
HD
...
hidemobilecontrols
...
hidecontrols
...
customCSS
...
customLogo
...
adsControlPositioning
...
logo
...
hideLogoOnAd
...
hideControls
...
contentUrl
...
showpreloader
...
preloader
...
contentClickThrough
...
, h: Number }] | Specific dimensions for the creatives to be rendered to this placement. | |||
autoStart | No | true | Boolean | Immediately start showing an ad after the initialization |
refresh | No | Object | Refresh policy config | |
strategy | No | interval | “interval”, “none” | Auto-refresh an ad or manually control it via API |
minViewTime | No | 5 000 | Number | Minimum time in milliseconds an ad should be in view before the next refresh |
minRenderTime | No | 30 000 | Number | Minimum time in milliseconds (30 000 / 60 000 / 90 000) between refreshes |
noNewInventory | No | false | Boolean | Don’t send inventory reporting |
maxRun | No | 9999 | Number | Maximum number of waterfall runs in the player session |
maxImp | No | 9999 | Number | Maximum number of impressions per player session |
errorLimit | No | 5 | 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 |
ref1 | No | String | Macro list ref1: “AV_MACRO1=value1&AV_MACRO2=value2“ Values should be URL encoded | |
clickThrough | No | Object | Show or not the skip button | |
url | No | String | Clickthrough url when clicking on the ad |
Placement API
avDisplay(placementConfig)
Instantiate the placement object with the placementConfig configuration.
width
Returns the placement width in pixels.
height
Returns the placement height in pixels.
hasLoadedAd
Returns whether we have a ready ad to render for this placement.
adWidth
Returns the ad width in pixels inside the placement.
adHeight
Returns the ad height in pixels inside the placement.
next(force: boolean)
Start/resume the placement instance, including ad flow. force flag means you want to kill the current refresh.minViewTime and refresh.minRenderTime timers and force the next ad to be requested instead of showing again the current ad if these timers didn’t pass yet.
stop()
Stop the placement, including ad flow.
requestBids()
Allows manually request bids if the refresh strategy is “none”.
renderAd()
Allows manually render the next winning bid’s HTML if the refresh strategy is “none”.
showAd()
Shows the ad inside the placement.
hideAd()
Hides the ad inside the placement.
on(evt, func)
Register an event listener for placement events.
destroy()
Close the placement and stop its functionality completely.
Placement 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 | ||
|---|---|---|---|
AdImpression | Called when there is an impression, regardless of creative type.
| ||
AdError | 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 | ||
Inventory | Called when the player is initialized | ||
InventoryRequest | Called every time the player starts a waterfall run | ||
AdShow | Will be triggered on each | ||
AdHide | Will be triggered on each |
Sample Events
Player Initialized Event
The player is initialized on the inventory event
| Code Block | ||
|---|---|---|
| ||
player.on("Inventory", function () {
// Player is initialized
}); |
Impression Event
| Code Block | ||
|---|---|---|
| ||
player.on("AdImpression", function () {
// Ad impression occured
}); |
Identify when the Player Finished Calls
An AdError event is called every time a set of 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
| Code Block | ||
|---|---|---|
| ||
player.on("AdError", function (event) {
if (event.detail.errorlimit) {
// Player stopped
}
}); |
Placement Behavior
The player support advanced behaviors 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
| Code Block | ||
|---|---|---|
| ||
<div style="width: 100%; margin: 0px auto; max-width: 640px;">
<div id="aniBox" style="height: 1px;">
<div id="aniplayer_aniviewJS562811134">
</div>
</div>
</div> |
The player template generator automatically build this structure
The player is created inside the position div with a unique id
Templates Configuration
The templates configuration ads additional configurations to placementConfig.
Name | Mandatory | Default Value | Values | Description |
|---|---|---|---|---|
reqOnView | true | 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 | |
startOnView | true | 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 | |
vitab | false | Boolean | If set to true, tab viewability is taken into account when checking viewability |