AdMan SDK is a library that is embedded into a video player and displays an ad, providing support for VAST/VPAID.
AdMan SDK embeds video ads into the content on websites of VK Ad Network's partners, and any third-party video player can be used to play the videos.
Integration instruction
The SDK mode returns a player object that provides methods to control it.
Accordingly, there is no way to control the player's behavior, and ads are loaded when the player starts.
The ad starts when more than 50% of the ad unit can be seen by the user.
In the SDK mode, working with AdMan3 player consists of two steps:
- Core initialization
- Creating a player instance
AdMan SDK core initialization
In cases where only the core AdMan SDK is initialized without creating player instances, place the code in the head or body section of the webpage:
<script async src="https://ad.mail.ru/static/vk-adman.js?sdk=1"></script>
It is crucial to specify the sdk variable with any value (?sdk=1). As a result, an AdMan SDK interface will be created at the browser level in the window object of the current web page to produce player instances.
Creating an AdMan3 player instance
After downloading and initializing the AdMan SDK core to display ads, create one or more instances of the player, saving them respectively to one or more variables (or to an array/object) for further use. Example of creating an individual player instance:
const player = new window.AdManSDK();
For further work with the player, call player methods, for example, player.pause().
Example of creating ten player instances:
const players = new Array(10);for (let i=10; i--;) { players[i] = new window.AdManSDK();}
or
const players = [];for (let i=10; i--;) { players.push(new window.AdManSDK());}
Each instance created is completely independent of other instances. It is initialized in an individual container and controlled by calling the methods of the corresponding instance.
Primary instance initialization
For initialization, call the init method of a previously created instance.
Possible configuration keys and their values:
| Key | Type | Value | Description |
|---|---|---|---|
| container | string | string[] | By default: #adman-ads | CSS selector or selector array of the html element in which the player will be placed. |
| slot | string | Placement ID – required fields with ad unit identifier. You can find it in the block settings after creating the block. | |
| slot | string | By default: "preroll" | "preroll" | "midroll" | "postroll" | “pauseroll” |
| dataAdQuery | string | Parameters transmitted: dl (urlencode string) – a mandatory parameter with the URLs hosting the player; content_id (integer) – recommended parameter with content (video) identifier on the partner's website. |
Example of player instance initialization:
const player = new window.AdManSDK();const initConfig = { container: "#adcontainer", slot: 1133888};const result = player.init(initConfig);
In the above example, the initialization process on the web page searches for a container with the adcontainer identifier in which the elements required for the ad display will be created. The ad information will be requested from ad unit 1133888. The ad request is a part of the initialization process.
Methods can be called without saving the result of execution:
const player = new window.AdManSDK();const initConfig = { container: "#adcontainer", slot: 1133888};player.init(initConfig);
When the instance is successfully initialized, the onReady callback is called.
Start of ad display
An ad must be expressly started by calling the start method (without parameters):
const result = player.start();
Note that calling the start method may not directly start the ad display if the user can see less than 50% of the ad unit height. In this case, the display of ads will begin as soon as at least 50% of the ad unit height is within the user's line of sight. The ad display is also suspended (paused) if more than half of the ad unit is out of visibility.
If the start method (or any other ad display control method) is called, error 5002 (NotInited) returns for the player instance that has not been initialized. Calling the start method for an instance with an ad that is already playing will return error 5006 (AlreadyStarted), while calling it for a deinitialized instance will return error 5007 (Destroyed). Also note that the start method is not used to resume suspended (paused) ads – for this, use the resume method.
Errors 5002 (NotInited) and 5007 (Destroyed) are returned in these cases and when other control methods are called.
The onStarted and onPlayed callbacks are called when the ad has started successfully.
Events and codes of Adman3 player
For events and codes of Adman3 player please follow the link
Display suspended (paused)
In addition to pausing the display of ads in cases where the user can see less than half of the ad unit height, the ad can also be paused by calling the pause method (without parameters):
const result = player.pause();
When the display is paused, the container continues to show the current ad fragment and the countdown stops. The relevant provisions specified in the previous sections apply to the result returned by the method and the possibility of ignoring it. If the method is called again (ad paused), error 5004 (NotPlaying) is returned.
The onPaused callback is called when the ad has been paused successfully.
Resuming the display
The resume method (without parameters) is used to resume playing the ad:
const result = player.resume();
If the method is called when the display is not paused, error 5005 (NotPaused) returns.
The onPlayed callback is called when the ad has been successfully resumed.
Stopping the display
The stop method (without parameters) is used to stop playing the ad:
const result = player.stop();
During the stopping process, the player instance is reset (deinitialized). Subsequent calls of control methods will return error 5002 (NotInited). In addition, all elements of any given player instance are removed from the web page.
The onClosed callback is called when the ad has been successfully stopped.
Skipping the ad
Use the skip method (without parameters) to skip the current ad and move to the next ad in the unit:
const result = player.skip();
If there is no next video to show, the player instance is reset (deinitialized).
The onSkipped callback is called when the ad has been successfully skipped.
Instance deinitialization
To force a reset (deinitialization) of a player instance, the destroy method (without parameters) is used:
const result = player.destroy();
Unless the instance has been initialized, the method call will return error 5002 (NotInited). Calling the method on an instance that has already been deinitialized will return error 5003 (AlreadyDestroyed).
Unlike calling the stop method, calling the destroy method does not call the onClosed callback.
If the method is successful, the internal data structures of the instance will be cleared and the elements of the respective player instance will be removed from the web page. The instance can then be reinitialized with the new configuration.
Volume control
The setVolume method with a single numeric parameter defining the volume level is used to control the ad sound volume (if the ad is accompanied by an audio):
const result = player.setVolume(0.5);
The volume values ranges from 0.0 (sound off) to 1.0 (maximum volume).