Adcontroller
Implementation AdController framework
Overview
The AdController provides a script deployment framework for the initialization and rendering of an ad request for of a specific supply page.
The implementation of the script deployment is to be implemented in the <head> tag of the page for the optimized provision of the service configuration as well as controllability of the process-related code execution. The script works 100% asynchronous and does not use blocking script code. If the <head> tag cannot be accessed for technical reasons, an implementation must be built into the document body before the first ad request (only after explicit agreement with iq). Initialization of the AdController (AC) should take place as early as possible and is a prerequisite for the subsequent AdController.render calls for ad request. If this is not possible or if advertising technologies are required depending on events (e.g. after page load), please consult iq digital separately.
This documentation assumes in advance that your offer is a classic web site consisting of several HTML documents linked to each other. This means that whenever a page is reloaded or subpages are opened, a browser refresh takes place. In case you make use of a single-page web application, you should also follow the steps in the section Single page application (no pageload).
If only editorial elements of the same page are reloaded asynchronously (e.g. image galleries without page refresh), the AdController offers a callback function for reloading the ad positions for this purpose. Here the steps from section Single page application (no pageload) can be ignored. The publisher is responsible for the event binding for triggering the callback in consultation with iq digital ( see section Callback function for reloading ad positions).
Hosting & Integration AdController
There are two different ways to implement the AdController on your pages:
- Retrieving the AC-Script-Deployment from an external web host of iq digital (AWS-CDN)
- Hosting and retrieval of the AC deployment from the iq-CDN
- Retrieve the AC-Script-Deployment from the web server of the site operator (recommended)
- As an alternative to hosting and directly retrieving the AC deployment from the iq-CDN, a direct implementation of the ad controller via the web server of the site operator is recommended. The prerequisite is a continued flexible connection of the AC-Deployment as PRELIVE and SANDBOX version by the iq-developer using iqdeployment parameters. There are already various implementations in use, which we would be happy to test with you.
Caching strategy AdController
For an optimized result regarding performance and current version of the AC deployment, we will be happy to discuss possibilities for short-term caching as well as expire time with you.
Delivery mode
The variable iqd_mode (see code example for the implementation of AdController) references the planned LIVE version of the AdController, or a version that differs from LIVE (e.g. PRELIVE or SANDBOX version of the AC deployment). The URL parameter extension "?iqdeployment=[placeholder]" enables the iq developer to test or deploy a pre-release version of the AC deployment during live operation without changing the website or implicating the website visitors.
Code example for implementation in the <head> tag of the document (separation of the script blocks is required)
The value for the macro [cdn_partnersite] is provided by iq.
<script>
function IQSLoader(url) {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = url;
document.getElementsByTagName("head")[0].appendChild(script);
}
var iqd_mode = (function () {
var dm = window.location.href.toLowerCase();
return (dm.indexOf('iqdeployment=') > 1) ? dm.split('iqdeployment=')[1].split('&')[0] : 'live';
})();
//CASE 1:
IQSLoader("https://s3.eu-central-1.amazonaws.com/prod.iqdcontroller.iqdigital/[cdn_partnersite]/" + iqd_mode + "/iqadcontroller.js.gz ");
//CASE 2:
IQSLoader("https://[publisher_directory]/[cdn_partnersite]/" + iqd_mode + "/iqadcontroller.js.gz");
</script>
<script>
(function () {
window.AdController = {
i: null, // page info q: [], // render queue
f: false, // is finalized s: false, // is staged
n: false, // is initialized r: null, // ready function c: [], // command queue
setPageInfo: function (i) {
window.AdController.i = i;
},
stage: function () {
window.AdController.s = true;
},
initialize: function () {
window.AdController.n = true;
},
render: function (n, c) {
window.AdController.q.push([n, c]);
},
finalize: function () {
window.AdController.f = true;
},
ready: function (callback) {
window.AdController.r = callback;
},
startLoadCycle: function () {
window.AdController.c.push(['startLoadCycle']);
},
reload: function (p, t) {
window.AdController.c.push(['reload', p, t]);
},
reinitialize: function (i) {
window.AdController.c.push(['reinitialize', i]);
}
};
})();
</script>
Client's CMS object (page information used for configurating the AdController)
Overview
In order to determine the configuration to be used for the current offer page, the AdController is provided with the necessary information about this object from the page operator (description follows under point: Client CMS object) This must be coordinated with iq digital in advance). The CMS object serves as a mediator between the AdController and the client‘s content management system (CMS).
Code example for the implementation in the <head> tag of the document after the AdController integration:
<script>
// ########### CMS object #############
var cmsObject = {};
cmsObject = {
$handle: "[Takes place after consultation with iq]",
level2: "[Takes place after consultation with iq]",
level3: "",
level4: "",
isWrapperApp: [true,false],
keywords: "[Takes place after consultation with iq]",
tma: "[Takes place after consultation with iq]",
platform: "[desktop | tablet | mobile]"
};
</script>
Object keys
key: $handle
The handle is used to match the page in question to a configuration template, tailored to a group of pages. These pages could have been grouped based on a specific layout type they share. As far as possible, iq digital supplies the $handle identifiers for the defined layout clusters - e.g. homepage ($handle:'homepage'), category and sub-category pages ($handle:'index'), article pages ($handle:'artikel') - which are relevant for the matching and have been agreed upon beforehand. Depending on the editorial layout structure and the requirements for controlling the web presence, a granular or flat $handle clustering may be necessary. For optimal allocation, the site operator must provide a site map with agreed and "open" layout $handle allocation.
keys: level2,level3,level4
These contain information on the content of the page in question. The way an AdServer is normally structured is that it mirrors the site's sections and sub-sections to a certain extent. These are called zones. For example, level2 = 'politik' and level3 = 'innenpolitik'. Ad campaigns within the AdServer could have been booked exclusively for articles dealing with transatlantic politics.
key: isWrapperApp
This value contains the information whether the delivery is in a wrapper app or not. Possible values for this are true or false.
key: keywords
The values from level2, level3, level4 can be added here. In addition, further keywords can be optionally added here, which describe the page and can help for better campaign targeting.
key: tma
This value is optional, but should be filled if this is a theme page or theme subpage. The value here is the name of the theme.
key: platform
Possible values here are: desktop, tablet, mobile. Please fill in the appropriate value depending on which page layout is active.
Character limitation
All information in the CMS object must be written in lower case. Spaces and special characters are not allowed. The only exception is the "_" character (underline/underscore).
WRONG: Archaeology CORRECT: archaeology WRONG: psychology-brain research Correct: psychology_brain research WRONG: nägel Correct: naegel
AdController initialization
After setting the cmsObject, the AdController must be initialised as follows:
<script>
if (!AdController._initialized) {
AdController.setPageInfo(cmsObject);
try {
AdController.stage();
} catch (e) {}
AdController.initialize();
} else {
(function checkDOMReadyState(c) {
try {
if (AdController.getRenderController().isReady()) {
AdController.reinitialize(cmsObject);
}
} catch (e) {
if (c < 50) {
c++;
setTimeout(function () {
checkDOMReadyState(c);
}, 100);
}
}
})(0);
}
</script>
Client sitemap (overview AdController-$handle assignment)
For a better understanding of your website structure and its administration in your CMS, it is desirable to provide a site map of the offer as shown below "exemplary". Furthermore, the clarification of the following questions is important for the AC implementation.
Generation of a general understanding of client content management
- Which offers are operated via the own editorial system?
- Which offers are operated by external service providers (content partners). Are there different requirements for AC implementation, e.g. cross-domain integration via IFrame?
- Which clusters, limitations for the offer control and management are given by the CMS layout templating?
Which offers are currently not marketed and will not integrate an AdController in the future?
Which offers are currently marketed but may not be implemented immediately or at the agreed timing with the AdController?
- Problem: Different AdServer technologies may be used in parallel
- Timing required, when these offers will follow
Assignment of CMS layout templating to AdController $handle cluster
- The possibility of making an individual tagging configuration effective for a specific offer area is only possible if a separate AdController handle is assigned for the configuration selection in AC deployment
- Usually the $handle-cluster is layout-based (e.g. homepage, ressort pages, article pages, ...) since the marketing requires appropriate product packages for the surrounding marketing and advertisement positions are often layout-dependent
- The objective is not to provide a separate $handle cluster or configuration for each different layout in the offer, but to combine non-relevant or product-independent reach offers into suitable clusters. The basic principle applies - as many $handle identifiers as necessary, as few as possible. iq can compress several clusters provided by the editorial team for this purpose, so that although a granular identifier is provided, the same configuration is always executed in the AdController. One advantage is that iq digital can assign specific configurations in these cases after such bundles have been resolved, if required at another point of time
Ad placeholder container model
The positioning of the placeholder containers for the ad placements in the publisher site follows the pre-agreed placement/tagging plan. The integration of the container itself should be according to the following sample.
<div class="iqdcontainer" data-placement="pos_[N U M M E R]" data-device="[D E V I C E T Y P E]"></div>
For the right identification of all placeholders every placeholder div-container must containt the following Information.
- The class "iqdcontainer". This class is a marker for all placeholder div-container.
- The data attribute "data-placement". Due to this data-attribute every position in the site can be addressed unambiguously.
- Das Data Attribute "data-device". This data attribute identifies if a placeholder div container is intended for desktop, mobile or tablet advertisement. possible values: desktop | tablet | mobile
Special Positions
All positions in footer and header do not receive a number in "data-placement", instead they are unambiguously determined by the values "pos_header" and "pos_footer".
<div class="iqdcontainer" data-placement="pos_header" data-device="[D E V I C E T Y P E]"></div>
<div class="iqdcontainer" data-placement="pos_footer" data-device="[D E V I C E T Y P E]"></div>
Signals & Ad structure
AdController.render(..)
After the AdController is initialized, it is ready to send an ad request to the AdServer. An ad request is triggered by the respective ad placement with the corresponding AdController.render method. In the render phase of the AdController, the level information of the CMS client object is passed to the AdRequest Builder and combined with other configuration parameters of the deployment to built an AdServer-compliant ad request.
Which ad placements are to be implemented for the respective layout of your website should be discussed in advance with iq digital regarding marketing possibilities. The ad placement is to be implemented by a unique DOM element with exemplary id=iqadtileT I L E N U M B E R in your HTML-MarkUp. The passed position key within the AdCongroller.render call causes an asynchronous integration via DOM insertion of the delivered ad in the target container.
Please do not insert any other DOM or script components within these ad containers. The ad labelling of the ad placements is best done by iq digital. We would be happy to discuss this point with you.
TopBanner constuct
Ad placement TopBanner construct, includes the first position iqadtile1 and both sky positions (please implement 1:1 the same way):
<!-- please use this construct for the top positions (iqadtile1), the sky right part (iqadtile21) & the left sky part (iqadtile20) and the out-of-page position (iqadtileOOP)-->
<div id="iqadtileOOP">
<script>
AdController.render('iqadtileOOP');
</script>
</div>
<div id="iqd_mainAd">
<div id="iqd_align_Ad">
<div id="iqd_topAd">
<div id="iqadtile1">
<script>
AdController.render('iqadtile1');
</script>
</div>
</div>
<div id="iqd_leftAd">
<div id="iqadtile20">
<script>
AdController.render('iqadtile20');
</script>
</div>
</div>
<div id="iqd_rightAd">
<div id="iqadtile21">
<script>
AdController.render('iqadtile21');
</script>
</div>
</div>
</div>
</div>
additional ad postions
Implement all further placements according to the following pattern:
<!-- please use this pattern for all other positions -->
<div id="iqadtileT I L E N U M B E R">
<script>
if (typeof AdController !== 'undefined') {
AdController.render('iqadtileT I L E N U M B E R');
}
</script>
</div>
AdController.finalize(..)
With the AdController.finalize call, the web page signals the AdController that the rendering phase can be completed because no further ad requests from the page are implemented. In some cases, the planned AdController configuration for the current page may differ from the actual implemented ad placements. In this case, the AdController evaluates the deviations, intercepts them and logs them if necessary. Deviations can always occur if no specific $handle assignment has been planned for the offer in question. This can also be a scenario desired by iq digital.
<script>
AdController.finalize(); // insert this after the last ad call
</script>
IQDComplete() - Pageload signal
As soon as all content on the page (including delayed dynamically loaded content) that contributes to the height calculation of the page has been loaded, a signal should be sent to iq digital:
<script type="text/javascript">
var IQDComplete = {
init: function () {
return true;
}
};
</script>
Test environment
In order to ensure that the AdController is implemented properly and guaranteed with regard to the operational readiness of the websites and to ensure that current and future marketing concepts by iq digital can be implemented, it is necessary for the AdController to use a full development environment for the initial adjournment of the pages.
The aim is to ensure that the AdController is implemented on a parallel system that is provided LIVE, once the final setup and testing has been completed by both parties.
The AdController for the web pages will be made available through various channels. Changes and further developments in the context of configuration adjustments or technology expansion for a site are carried out digitally by iq via a preview deployment. The current integration of the AdController already provides for a dynamic switch between LIVE and PRELIVE versions of the AdController, which can be controlled on the client side with a GET parameter extension in the URL "https://www.domain.com?iqdeployment=prelive".
The CMP used on the live page should also be implemented on the test page.
Fluids / Responsive sites
If you operate a fluid or responsive web application to maintain different channels within the stationary desktop and mobile web with leaner code and a uniform editorial system, coordination of the points relevant for marketing is necessary in advance. In the case of the AdController, this means that ad placement concepts for desktop web and mobile must be plausibly coordinated with each other. Please provide iq digital an overview of your layout solution, including planned breakpoints, any adaptive layout adjustments and device detections.
When switching from desktop web layout to mobile-optimized view, a separate AC Mobile deployment is required as soon as your device detection code identifies the corresponding environment. In addition, the ad placements of the desktop web cannot be transferred 1:1 to the mobile-optimized design at that time because the number and position of the placements do not match the different marketing requirements of these environments when the HTML markup is fluidly rearranged. Please consult with iq digital to agree on an appropriate placement concept.
The corresponding requirements and concepts are already in use in iq digital's marketing portfolio, and we would be happy to provide assistance within the scope of active implementations.
Single page applikation (no pageload)
The client must ensure in the case of an SPA implementation during page navigation that:
- cmsObject must be re-set
- AdController must be reinitialised
- Render functions must be called again
- a postMessage() message is sent to us ( see section Callback function for reloading ad positions)
Callback function for reloading ad positions
The following postMessage must be sent to iq as soon as this has already been coordinated with iq in order to trigger a reloading of the advertisements:
<script type="text/javascript">
window.top.postMessage("iq_refresh_ads","[targetOrigin]");
</script>