Adserver Developer Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Creating and managing banners for the easyHTML template ======

===== Introduction =====

The easyHTML template is a Markup tamplate, which is ment to make managing HTML banners easier. This template also utilizes ''<iframe>'' to show the banner in, but managing this is a lot quicker. This holds benefits for both the management of the creative, and developing it.

===== Creating the banner =====

==== Introduction ====

The easyHTML template is such a tool int the Adverticum AdServer, that helps converting and managing the HTML/HTML5 banners. When developing such a banner, we should prepair, that the banner will be placed in an ''iframe'', and it has to be able to utilize the recieved ''GET'' variables.

To help in this, we provide a ''javascript'', that should be included in the ''<head>'', which does parse the mentioned variables, and registers the necessary functions. This tool is called ''goa-helper.js'', and on the usage, please refer to the guide after the restrictions.
==== Restrictions ====

**1.** By using the above mentioned tool, there are protected names, which can be changed except for ''goa''.

  * ''goa''
  * ''closeFunction''
  * ''openFunction''
  * ''hideFunction''

In case the banner recieves measure points, the name of those will be also protected, along the scheme beneath, This should be checked with the campaign manager! 

  * ''[name]_fire''

For example if it's called ''bubble'':

  * ''bubble_fire''

**2.** The banner cannot use a folder system! Each file has to be in the same directory as the main ''.html''.

<code html>

<img src="images/myImage.png" />

</code>

So the above wil have to be changed to this:

<code html>

<img src="myImage.png" />

</code>

**3.** All files have to have unique names, related to the banner, because they will be copied in the same folder as the other banners running in the same campaign.

**4.** All file size has to be under 300KB!

==== Prepare for serving  ====

We have to prepare for the fact, that our banner will be served in an iframe. This document will not contain anything other then what we insert, so we have to make sure that CSS margins, paddings, etc. are reseted, and hide the scroll bars in certain cases.

For this, we recommend using the snippet below, but other properties might be needed in some banner structures. This should be placed before any other CSS, to avoid overwriting of other CSS properties the banner needs.

<code html>

<style>
    body {
        margin: 0;
        padding: 0;
        border: none;
        
        overflow: hidden;
    }
</style>

</code>

==== Including goa-helper.js ====

To include ''goa-helper.js'', just paste the following code in the ''<head>'' of the banner. All the functions and references to ''goa'' has to be after this script.

<code html>

<script src="//ad.adverticum.net/scripts/goa-helper.js"></script>

</code>

==== Checking open start request ====

Certain display modules (''MultiExpand'', ''Billboard'', ''Sidekick'', ''Slider'') can be set to start in open state. This is handled by the Goa3 script. It is signaled to the banners, and can be checked like so:

<code javascript>

if (goa.openNow === 'true') {
/*...*/
}

</code>

In this ''if'' statement comes the code that should be called if the banner opens. For example resizing the content, or playing ceratin animations, that should be done if opened.
==== Handling clicks in case of one URL ====

To handle basic clickthrough, we need to read ''goa.clickTAG'', and apply it in the prefered manner. This also has aliases:

  * ''goa.clickTAG''
  * ''goa.clickTag''
  * ''goa.cthref''

Adminunkon beállítható, hogy a landing page hol nyíljon meg pl. ''_self'' vagy ''_blank'', amit a ''goa.clickTARGET'' változóban adunk át. Alternatív nevei:

Tha target window to load the CT URL can be set on our admin site, eg.: ''_self'' or ''_blank'', which can be read from ''goa.clickTARGET''. Available with aliases:

  * ''goa.clickTARGET''
  * ''goa.clickTarget''

=== HTML example ===

<code html>

<a id="clickTAG" href="" target="">CT</a>
<script>
    (function(){
    
        var cT = document.getElementById('clickTAG');
        cT.href = goa.clickTAG;
        cT.target = goa.clickTARGET;
    })();
</script>

</code>

=== JS example ===

<code html>

<div id="clickTAG"></div>
<script>
    document.getElementById('clickTAG').onclick = function () {
        window.open(goa.clickTAG, goa.clickTARGET);
    }
</script>

</code>

==== Handling clicks in case of multiple URLs ====

Handling multiple CT URLs shoud **not** be done through ''goa.clickTAG''. We have the option to set custom variables, thorugh adding extra parameters when uploding to our servers.

We have to attach a ''JSON'' object, for the campaign manager to include while uploading the banner. In this we have to use the awaited names of the links as keys, and the URL itself as the value. Attaching it as a separate file with the extension of .txt is recommended. For example:

:!: **It is essential that the ''JSON'' does not contain broken lines, just a single one. To minify it, there are several free online tools available, for example: [[http://www.willpeavy.com/minifier/]]**

:!: **Further neccesity is that the both the keys and values are written in double quotes. To check the validity of the object, we can use the following site: [[http://jsonlint.com/]]**

<code javascript>
{"clickTAG0": "//missinglink.adverticum.net/", "clickTAG0": "//check.adverticum.net/"}
</code>

While displayment, the link will be available by getting the properties form the ''goa'' object we define in this ''JSON''.

=== HTML example ===

<code html>

<a id="clickTAG0" href="" target="">CT</a>
<script>
    (function(){
    
        var cT = document.getElementById('clickTAG0');
        cT.href = goa.clickTAG0;
        cT.target = goa.clickTARGET;
    })();
</script>

</code>
=== JS example ===

Managing the second URL:

<code html>

<div id="clickTAG1"></div>
<script>
    document.getElementById('clickTAG1').onclick = function () {
        window.open(goa.clickTAG1, goa.clickTARGET);
    }
</script>

</code>

==== Handling the functions ====

The ''goa-helper.js'' registers several functions under the ''window'' namespace. these are usualy open and close functions, and in case of Slider display, hideing function is registered. the name of these functions are set in the ''GET'' variables. These can be modified by overwriting them in the extra parameters ''JSON''.

<code javascript>
{"closeFUNCTION": "myCloseName", "openFUNCTION": "myOpenName", "hideFUNCTION": "myHideName"}
</code>

**On the topic of available functions of display modules:\\
[[http://dev.adverticum.com/creatives:html-en#using_display_module_functions]]**

==== Close ====

Default value is ''closeFunction'', and can be retrieved from:

  * ''goa.closeFUNCTION''
  * ''goa.closeFunction''

=== HTML example ===

By using the default value:

<code html>

<div onclick="closeFunction();">OPEN</div>

</code>

=== JS examaple ===

By using the default value:

<code html>

<div id="closeButton"></div>
<script>
    document.getElementById('closeButton').onclick = closeFunction;
</script>

</code>

Or using the dynamic method:

<code html>

<div id="closeButton"></div>
<script>
    document.getElementById('closeButton').onclick = window[goa.closeFUNCTION];
</script>

</code>

==== Open ====

The default value is: ''openFunction'', and can be retrieved from:

  * ''goa.openFUNCTION''
  * ''goa.openFunction''

=== HTML example ===

By using the default value:

<code html>

<div onclick="openFunction();">OPEN</div>

</code>

=== JS example ===

By using the default value:

<code html>

<div id="openButton"></div>
<script>
    document.getElementById('openButton').onclick = openFunction;
</script>

</code>

Or with the dynamic method:

<code html>

<div id="openButton"></div>
<script>
    document.getElementById('openButton').onclick = window[goa.openFUNCTION];
</script>

</code>

==== Hide ====

This is only needed in case of developing for the Slider display's secondary, sidekick banner, which can hide itself. Using the closeing function would remove the main creative which could lead to errors.

The default value is ''hideFunction'', and can be retrieved from:

  * ''goa.hideFUNCTION''
  * ''goa.hideFunction''

=== HTML example ===

By using the default value:

<code html>

<div onclick="hideFunction();">HIDE</div>

</code>

=== JS example ===

By using the default value:

<code html>

<div id="hideButton"></div>
<script>
    document.getElementById('hideButton').onclick = hideFunction;
</script>

</code>

By using the dynamic method:

<code html>

<div id="hideButton"></div>
<script>
    document.getElementById('hideButton').onclick = window[goa.hideFunction];
</script>

</code>

==== Using the measures provided ====

If the creative has measures available, the name of the measure is passed buy the template. These names are used to register functions by the ''goa-helper'' for the banner to use. So if the banner recieves a measure called ''bubbles'', then the generated function name will be ''bubble_fire''.

=== HTML example ===

<code html>

<div onclick="bubbles_fire();">HIDE</div>

</code>

=== JS example ===

<code html>

<div id="hideButton"></div>
<script>
    document.getElementById('hideButton').onclick = bubbles_fire;
</script>

</code>

----

===== Uplodaing the banner =====

==== General ====

  - To upload the banner create a Markup banner.
  - Name the banner.
  - Set banner dimensions. :!: **It is crucial to set the right banner size, as will be used to display it in!**
  - Choose the ''Templates'' tab.
  - Choose ''easyHTML Banner'' from the template drop down menu.
  - Set ''Banner file'' by choosing the ''.html'' from the drop down. If not uploaded yet, use the ''+'' signed button to add files.

==== Adding extra parameters to the banner ====

There is the option to add extra parameters, like multiple CT URLs for the banner. These are needed to be pasted in the ''Extra parameters'' text box, in the manner below. This object has to come with the banner, provided by the developer.

<code javascript>

{"clickTAG0": "//missinglink.adverticum.net/", "clickTAG1": "//check.adverticum.net/"}

</code>

This will be recieved by the tamplate and passed to the banner. If there is a need for extra parameters, please consult the developer to use the proper variable names. 

In the example the two parameters are ''clickTAG0'' and ''clickTAG1''. These provide multiple CT URLs fot the banner.

  - Click ''Source'' tab.
  - Click ''Add new URL'' button under the list of ''URL''s.
  - Create URLs according to the recieved extra parameters. :!: **Attention! All URLs are measured as CT.**
  - Take a note of the URL's ID or name.
  - Click the ''Template'' tab, and insert into''Extra parameters'' box the recieved object modified this way:

<code javascript>
{"clickTAG0": "[url:100000]", "clickTAG1": "[url:200000]"}
</code>

:!: It very important to use double quotes both on the key and value.

When done in reality, the numbers will be the URL IDs.

----