Documentation

Adcontroller: Difference between revisions

Created page with "==Implementation AdController framework== ===Overview=== The AdController provides a script deployment framework for the initialization and rendering of an ad request for of..."
 
No edit summary
 
(11 intermediate revisions by 3 users not shown)
Line 42: Line 42:


     var iqd_mode = (function () {
     var iqd_mode = (function () {
        var dm = window.location.href.toLowerCase();
      let mode = 'live';
        return (dm.indexOf('iqdeployment=') > 1) ? dm.split('iqdeployment=')[1].split('&')[0] : 'live';
      const currentUrlSearchParams = new URLSearchParams(window.location.search);
 
      if (currentUrlSearchParams.has('iqdeployment')) {
        mode = currentUrlSearchParams.get('iqdeployment').replace(/\W/g, '');
      }
 
      return mode;
     })();
     })();


Line 92: Line 98:


<div class="page-break"></div>
<div class="page-break"></div>
==Client's CMS object (page information used for configurating the AdController)==
==Client's CMS object (page information used for configurating the AdController)==


Line 112: Line 119:
         keywords: "[Takes place after consultation with iq]",
         keywords: "[Takes place after consultation with iq]",
         tma: "[Takes place after consultation with iq]",
         tma: "[Takes place after consultation with iq]",
         platform: "[desktop | tablet | mobile]"
         platform: "[desktop | tablet | mobile]",
        userData: {
          hashedEmail: "[Hashed Email see explanation below]"
        }
     };
     };
</script>
</script>
Line 143: Line 153:


Possible values here are: desktop, tablet, mobile. Please fill in the appropriate value depending on which page layout is active.
Possible values here are: desktop, tablet, mobile. Please fill in the appropriate value depending on which page layout is active.
====key: userData====
“userData” is the collection object for all necessary user information, both in the context of clean room cases and our ID solutions.
=====key: userData:hashedEmail=====
Prior normalization and transfer of via SHA256 created hashes of email addresses after user login/newsletter registration.
<syntaxhighlight lang='javascript'>
//example of sha256 hash
const userData:{
        hashedEmail: "21bd991f8b25a57075dd2489b4eebda1a5d956bbf52f961fe5289c6d5a0a2b5c"
}
</syntaxhighlight>
'''Normalization''':
Before hashing the email address, normalize the character string by removing “superfluous” characters:
# Remove leading and trailing spaces.
# Convert all ASCII characters to lowercase.
# Remove "." (ASCII code 46) from the username of the email address.
  e.g., jane.smith@gmail.com is normalized to janesmith@gmail.com
# Remove "+" (ASCII code 43) and all subsequent characters from the username of the email address 
  à  e.g., janesmith+test@gmail.com is normalized to janesmith@gmail.com


===Character limitation===
===Character limitation===
Line 170: Line 209:
                 if (AdController.getRenderController().isReady()) {
                 if (AdController.getRenderController().isReady()) {
                     AdController.reinitialize(cmsObject);
                     AdController.reinitialize(cmsObject);
                } else {
                    throw new Error("renderController not ready");
                 }
                 }
             } catch (e) {
             } catch (e) {
Line 206: Line 247:


<div class="page-break"></div>
<div class="page-break"></div>
==Ad placements==
==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.


===Signals & Ad structure===
<syntaxhighlight lang='html'>


====AdController.render(..)====
<div class="iqdcontainer" data-placement="pos_[N U M B E R]" data-device="[D E V I C E T Y P E]"></div>


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.
</syntaxhighlight>


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.
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'''


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.
===Special Positions===


====TopBanner constuct====
====Header and Footer====


Ad placement TopBanner construct, includes the first position iqadtile1 and both sky positions (please implement 1:1 the same way):
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".


<syntaxhighlight lang='html'>
<syntaxhighlight lang='html'>
<!-- please use this construct for the top positions (iqadtile1), the sky right part (iqadtile2) & the left sky part (iqadtile20) -->
 
<div id="iqd_mainAd">
<div class="iqdcontainer" data-placement="pos_header" data-device="[D E V I C E T Y P E]"></div>
    <div id="iqd_align_Ad">
 
        <div id="iqd_topAd">
<div class="iqdcontainer" data-placement="pos_footer" data-device="[D E V I C E T Y P E]"></div>
            <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="iqadtile2">
                <script>
                    AdController.render('iqadtile2');
                </script>
            </div>
        </div>
    </div>
</div>
</syntaxhighlight>
</syntaxhighlight>


====additional ad postions====
==Ad placement signal functions==


Implement all further placements according to the following pattern:


<syntaxhighlight lang='html'>
<!-- 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>
</syntaxhighlight>


====AdController.finalize(..)====
===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.
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.
Line 277: Line 291:


<div class="page-break"></div>
<div class="page-break"></div>
====IQDComplete() - Pageload signal====
===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:
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:
Retrieved from "http://docs.iqd-ao.de/en/index.php?title=Adcontroller"