General Actions:
Call the ad server
Last modified by ZdVo on 2017/12/04 08:45
Now that everything is configured, we know what data we want to sent and which ad slots are managed by which ad server, we are ready to call the ad server for the ads.
There are actually various ways to do that depending on how much control you want to have, but in 99% of cases you will call the following method:
ibbAds.tag.requestAndPlaceAds();
This will call ALL configured Ad Servers, request ads for ALL configured Ad Slots and place the ads in their respective ad slots as they arrive.
As you can see, a lot is happening in that call.
You can have more control over which ad slots you want to fill with ads by providing arguments to the call. Let's explain it by example:
ibbAds.tag.requestAndPlaceAds(adserver); // will only request ads for ad slots managed by 'adserver', but not by 'adserver2'
ibbAds.tag.requestAndPlaceAds('BbmCz'); // will only request ads for ad slots managed by ad server 'bbmcz' - referenced by name
ibbAds.tag.requestAndPlaceAds(sky); // will only request ads for ad slot referenced by variable called sky - the tag will call the appropriate ad server as configured for the slot
ibbAds.tag.requestAndPlaceAds('skyscraper'); // will only request ads for ad slot referenced by name 'skyscraper' - the tag will call the appropriate ad server as configured for the slot
ibbAds.tag.requestAndPlaceAds(['skyscraper','bottom-right-ad-slot']); // will request ads for listed ad slots from their corresponding ad server(s) - it is also possible to pass in variables referencing ad slots and any combination of names and variables
ibbAds.tag.requestAndPlaceAds('BbmCz'); // will only request ads for ad slots managed by ad server 'bbmcz' - referenced by name
ibbAds.tag.requestAndPlaceAds(sky); // will only request ads for ad slot referenced by variable called sky - the tag will call the appropriate ad server as configured for the slot
ibbAds.tag.requestAndPlaceAds('skyscraper'); // will only request ads for ad slot referenced by name 'skyscraper' - the tag will call the appropriate ad server as configured for the slot
ibbAds.tag.requestAndPlaceAds(['skyscraper','bottom-right-ad-slot']); // will request ads for listed ad slots from their corresponding ad server(s) - it is also possible to pass in variables referencing ad slots and any combination of names and variables
Using these calls, you can for example first request the ads for the first 5 ad slots in the page which you know are almost always visible and only request ads for remaining 3 ad slots if the user scrolls down to a certain point etc.
You can have even finer control over requesting ads and placing the to the page, although in most cases it is not advisable to manual manage the process.
If you want to only request the ads (without placing them into their ad slots), you use the call:
ibbAds.tag.requestAds();
It accepts the same arguments as the requestAndPlaceAds call, so you can do it for only a chosen ad server instance or chosen ad slot(s). Because all calls to ad server are asynchronous, you will only receive a reference to "future" ads (the ads that will arrive in the future) and you have to handle that accordingly. For that, a method called whenAdsArrive is provided so that you can grab the ads as soon as the ad server returns them and do what you need to do with them. Here is the example of how you would do that:
ibbAds.tag.requestAds().whenAdsArrive(function(ads) {
// manipulate the array of ads returned from ad server
// not that this function will be called one time for each ad server from which the ads were requested and it may returned empty array of ads if no ad was returned.
});
Place the ads to the slots
This happens automatically if you use the standard requestAndPlaceAds call.
If you want to place the ads into their ad slots manually though for some reason, you can call:
ibbAds.tag.placeAds(ads); // an array of Ad definitions must be passed as argument
Note that each Ad definition contains already information about to which ad slot it should be placed. The ad slot(s) are emptied before placing a new ad to them.
You could actually completely skip calling the ad server and place the ads created by yourself (e.g. for debugging purposes). In that case, you have to create the ad definition first and then place it, e.g. like this:
var ad = ibbAds.tag.createAd(1); // argument is ad id
ad.setSlotMarkup('skyscraper', '<div>some html or script to be shown in skyscraper slot</div>');
ibbAds.tag.placeAds([ad]); // you can place multiple ads at once if you wish
ad.setSlotMarkup('skyscraper', '<div>some html or script to be shown in skyscraper slot</div>');
ibbAds.tag.placeAds([ad]); // you can place multiple ads at once if you wish
Clear ad slots
Ad slots are automatically cleared before any new ad is placed into them.
If you wish to clear them manually for some reason, you can call:
ibbAds.tag.clearSlots(); // accepts the same arguments as requestAndPlaceAds, so you can clear any group of ad slots you wish separately
Reload ads for ad slots
You can reload ads in ad slots by repeatedly calling requestAndPlaceAds described above.