Versions Compared

Old Version 4

changes.mady.by.user Orel Weinstock

Saved on

compared with

New Version Current

changes.mady.by.user Roman Shevchenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 instream or outstream players.

Placements extend the regular studio tag configurations in the following fashion:

The following properties from the Studio Tag are ignored by Placements:

  1. playOnView - playing or not depends on the type of creative to render, so for video creatives this config will be passed in separately.

  2. fullscreen - placements are creative-neutral

  3. pauseButton - assumes pause-able media, not creative neutral

  4. soundButton - assumes media has sound, not creative neutral

  5. showbigplay - assumes play-able media, not creative neutral

  6. autovolume - assumes media has sound, not creative neutral

  7. imaiosskip- assumes IMA is involved, video centric, not creative neutral

  8. autoPlay- assumes media is playable, not creative neutral

  9. replayFunc - assumes media is playable, not creative neutral

  10. ifrhandler- assumes media requires an iframe handler, not creative neutral

  11. startaddelay- assumes media is playable, not creative neutral

  12. startmidroll- assumes media is playable, not creative neutral

  13. backgroundColor- assumes media has background, not creative neutral

  14. nativetest - assumes media is a tested native video, not creative neutral

  15. nativevideo - assumes media is a native video, not creative neutral

  16. autosound - assumes media has sound, not creative neutral

  17. closeButtonStyle - assumes media is close-able, not creative neutral

  18. closeButton - assumes media is close-able, not creative neutral

  19. timelinechange - assumes media has timeline dependent position, not creative neutral

  20. noifsnd - assumed media has sound, not creative neutral

  21. skipText - placements have their own skip implementation

  22. vastRetry - assumes media is VAST, not creative neutral

  23. mode - setting for VAST, not creative neutral

  24. loopVideo - assumes media is a video, not creative neutral

  25. Midrolltime - assumes media is a video, not creative neutral

  26. loop - assumes media is a video, not creative neutral

  27. loopVideo - assumes media is a video, not creative neutral

  28. timelineMode - assumes media has a timeline, not creative neutral

  29. vastIconEnabled - assumes media is a video, not creative neutral

  30. lastFrame - 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

...

Table of Contents

Placement Element

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

Code Block
languagehtml
<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.

For example:

Code Block
languagejs
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/ads.js

Placement Instantiation

Code Block
languagejs
myPlacement = new avDisplay(placementConfig);

Putting it all together

Code Block
languagehtml
<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/ads.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,

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
(legacy name - interval)

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.
The AdImpression event passes 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
  }
}

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 showAd API call

AdHide

Will be triggered on each hideAd API call

Sample Events

Player Initialized Event

The player is initialized on the inventory event

Code Block
languagejs
player.on("Inventory", function () {
  // Player is initialized
});

Impression Event

Code Block
languagejs
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
languagejs
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
languagehtml
<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