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.
====== HTML/XHTML/HTML5 banner készítési útmutató ======

Ebben az útmutatóban a megrendelők által gyakran "HTML5 bannerként" emlegetett (de nem feltétlenül minden esetben HTML5-ben megírt) HTML/XHTML bannerekkel szemben támasztott AdServer-specifikus követelményeket foglaltuk össze, hogy a bannerkészítők munkáját segítsük. 

Az útmutató jelentős részben tartalmaz olyan, HTML kódok AdServerbe történő feltöltéséhez szükséges információkat, amiket elsősorban a kód feltöltését végző személynek, jellemzően a kampánymenedzsernek fontos tudnia, ugyanakkor ha a bannerkészítő ezeket az információkat figyelembe veszi a banner fejlesztésekor, akkor nagyban megkönnyítheti a kampánymenedzser dolgát.

Az útmutató feltételezi, hogy a készítendő hirdetés az Adverticum AdServer beépítési kódjával, a goAdverticum3 (a továbbiakban goa3-ként hivatkozunk rá) kóddal lesz kiszolgálva, illetve hogy a hirdetést kiszolgáló kód a goa3 kód dokumentációja szerint lett beillesztve a weboldalba, ahol a hirdetés megjelenik.

:!: **Figyelem! A Swiffyvel konvertált, ill. Adobe Edge vagy Google Web Developerrel készült bannerek esetén az alábbi útmutatót kövessük: [[http://dev.adverticum.com/conversion:start]]**

===== Fogalmak =====

==== HTML vagy Markup banner? Mit jelent, és mi a különbség az Adverticum AdServerében a két megoldás között? ====

A Markup banner nagyon hasonlít a normál HTML bannerhez, azzal a különbséggel, hogy az XHTML, XML sokkal kötöttebb formátumok, viszont felhasználói szempontból több lehetőséget biztosítanak. Technikailag lényeges különbség, hogy a Markup banner az oldal részeként jelenik meg, nem pedig iFrame-ben, mint a sima HTML banner. A Markup banner képes használni az oldal CSS-ét, illetve olyan extra funkciók válnak általa elérhetővé, mint a kinyíló és átúszó effektek, illetve egyéb látványos, vizuális megoldások. **Az XHTML, XML vagy HTML5 kódokat az AdServer ellenőrzi**, és jelzi, ha hibát talál. Az ellenőrzésre használt validátorokról bővebb információt itt olvashat: [[http://dev.adverticum.com/creatives:validatorok]]


===== easyHTML sablonhoz készülő kreatívokról =====

**Ennek használatát javasoljuk, és az erről szóló dokumentációnk itt érhető el: [[http://dev.adverticum.com/creatives:ehtml]]**

Megoldásunk célja, hogy megkönnyítsük az egyre terjedő HTML alapú kreatívok kezelését a kampánymanagerek és a kreatívosok számára egyaránt. Ezt egy Markup sablon formájában alakítottuk ki, melyet mindneki számára díjmentesen elérhetővé teszünk.

A kreatív elkészítése szempontjából sokkal egyszerűbb a folyamat, mert kreatívnak lényegesen kevesebb megkötésnek kell megfelelnie. Címszavakban a következő előnyökkel jár, szemben a HTML banner használatával:

  * Nem kell a banner szerkezetén változtatni, ha az a böngészőben már megfelelően működik, tehát nem kell kitörölni a ''<head>'' vagy ''<body>'' tagokat.

  * Nem lesz karakter enkódolási probléma, mely a ''HTML'' banner egy sajátosságából fakadt bizonyos esetekben.

  * Megoldott, és egyszerűsített a Display-ek vezérlése, különös tekintettel a Sidekick és Slider megjelenésekre.

  * Megoldott a nyitva indulás érzékelése, szemben a ''HTML'' bannerekkel.

  * Használhatóak relatív ''URL''-ek, ezeket nem kell lecserélni AdServer változókra.

  * A bannerhez tartozó változók és funkciók egy központi objektumból érhetőek el, nem AdServer változókkal.

  * Ezek mellett továbbra is van lehetőség rich media, ill. több landing-page-el rendelkező kreatívok futtatására.

----

===== A HTML bannerekkel (HTML/XHTML/HTML5 kóddal) kapcsolatos megkötések =====

:!: **Csak a body tartalmát kell beilleszteni, minden mást a szerver generál. A head-et is tartalmazó bannereket nem lehet feltölteni az AdServerbe, a feltétlenül a head-be szánt dolgokat scripttel kell megoldani.**

Gyakran előfordul, hogy egy HTML banner kódja relatív hivatkozást vagy hivatkozásokat tartalmaz külső fájlokra (általában képfájlokra vagy CSS-re). HTML banner készítésekor ügyelni kell rá, hogy a bannerhez tartozó fájlban (általában .css-ben) már ne legyenek további relatív hivatkozások fájlokra (általában képfájlokra). Inkább ezek a (kép)fájlok is legyenek kiemelve a HTML kódba. A bannert tehát úgy kell elkészíteni, hogy minden hivatkozás magában a HTML kódban legyen, ne a CSS-ben vagy a javascriptben.

A külön .css fájl használata helyett ajánlott egyenesen a html kódba tenni a szükséges részeket:
<code html>
<style type=”text/css”> … </style>
</code>

Előfordulhat, hogy mindenképpen külön fájlként szeretnénk feltölteni az AdServerbe a CSS-t. Ekkor így hivatkozzunk rá (ebben a .css a fájlban azonban már nem szerepelhet kép elérési útja):

<code html>
<link type="text/css" href="[file:fájlnév.kiterjesztés]" />
</code>

Képek használata pl. háttérképként így lehetséges: 

<code html>
<div style="background:url([file:fáljnév.kiterjesztés])"></div>
</code>

Ha külön töltjük fel scriptünket, amiben használunk fájlhivatkozásokat, akkor szintén nem használhatunk relatív útvonalakat, mert azok a szerverre feltöltve megváltoznak. Ebben az esetben ki kell emelnünk azokat a részeket a scriptből amik ezeket a hivatkozásokat tartalmazzák, és be kell illeszteni a HTML kódba a szokásos tagek közé:

<code html>
<script type=”text/javascript”>…</script>
</code>

Azonban ezt megfontoltan kell használni, mert többnyire a teljes kód beillesztése esetén a HTML kód mérete így meghaladja majd a 60kB-os határt, az AdServer pedig nem enged ennél hosszabb kódot elmenteni. Így tartózkodnunk kell a komplett könyvtárak beillesztésétől, és csak a szükséges objektumokra, ill. funkciókra kell korlátoznunk ezt.

**A kampánymenedzsereknek szóló részletesebb leírást a relatív hivatkozást tartalmazó html banner felvételéről itt talál:
[[https://support.adverticum.net/index.php?/Sales/Knowledgebase/Article/View/74/2/relatv-hivatkozst-tartalmaz-html-banner-felvitele]]**

===== Kattintások kezelése =====

==== Kattintások kezelése egy link esetén ====

A felhasználót a cél oldalra vivő kattintások kezeléséhez szükség van egy kattintható felületre. Ez lehet egy <a> tag, ahol a link helyére kell a ''[cthref]'' stringet illeszteni, amit kiszolgálás közben az AdServer ki fog cserélni a megfelelő URL-re, mely számol egy kattintást, majd átirányít a rendszerben megadott céloldalra.

<code html>
<a href="[cthref]" target="_blank" class="classname"></a>
</code>

Ez természetesen megoldható javascriptből is, ebben az esetben is a link helyére illesztendő a ''[cthref]'' kifejezés. Amennyiben URL encode-olt formában volna szükségünk a CT linkre, például ''GET'' paraméterben történő átadáshoz, használjuk a ''[cthref.e]'' kifejezést.

:!: **Mire kell odafigyelni, ha az elkészített banner Adverticum-Adverticum összefűzéssel fog megjelenni?**

Amennyiben ''<a>'' kódban a tagot használunk:

<code html>
<a href="[cthref]" target="_blank"></a>
</code>

Az így módosul:

<code html>
<a id="clickTAG" target="_blank" href="[cthref]" onclick="(function(){document.getElementById('clickTAG').href=HttpGetVars.cthref})();"></a>
</code>

Van lehetőség egyenesen kiolvasni a CT linket javascriptből, amit így érünk el. Ezt aztán a banner scriptje felhasználhatja a kattintást kezelő gomb elkészítéséhez.

<code html>
<script>
    var clickTAG = HttpGetVars.cthref;
</script>
</code>
==== Kattintások kezelése több link esetén ====

:!: **Több link esetén ne használjuk a ''[cthref]''-et.**

A kódban a ''[cthref]'' helyére ''[url:xxxxxxx]'' kerül, ahol az ''xxxxxxx'' helyén az URL rendszerbeli ID-ja szerepel. A banner feltöltésekor a kampánymenedzser az "Új URL hozzáadása" gombra kattintva létrehozza a megfelelő URL-eket, majd az adminfelületen megjelenő URL listában a kívánt URL-re kattintva az adminfelület automatikusan beilleszti a ''[url:xxxxxxx]'' stringet a kód azon részére, ahol a kurzor áll. Emiatt javasolt a kampánymenedzserrel egyeztetett módon jelölni a kódban, hogy hol melyik URL-t kell ezen módon beillesztenie.

A bannerkészítő szempontjából több link esetén mindig a fentiek szerint kell eljárni, viszont a kampánymenedzser munkája szempontjából más esetnek minősül, hogy a különböző linkekre érkező kattintásokat egyben vagy külön kell mérni. Bővebb információ erről a kampánymenedzsereknek szóló dokumentációkban található.
==== Paraméterek átadása <form> segítségével ====

Az AdServer képes paramétereket (''HTTP GET'') dinamikusan továbbítani a céloldalra. A továbbításhoz egy speciális paraméterre van szükség az AdServer meghívásakor.

A ''[cthref]'' értékét mindkét esetben az admin felületen a CT url mezőben kell megadni.

<code html>

<form method="get" action="[cthref]" target="_blank"> 

    <input type="hidden" name="fwdparams" value="1"> 
    <input type="text" name="parameter1">
    <!-- ... -->
    <input type="submit" value="Mehet">
</form>

</code>

----
===== Markup bannerként illetve mobil készülékeken futó kreatívokkal kapcsolatos kiegészítő megkötések =====

A Markup bannerek további megkötéseket kívánnak meg. Ezeket a rendszer ''JSONML'' formátumra konvertálja és kiszolgáláskor ebből építi fel, ezért a Markup bannerként futtatott, illetve mobil készülékekre szánt banner kódjának valid XHTML/XHTML5 kódnak kell lennie.

Mivel a bannerek beépítését végző goa3 kód DOM ready-re fut le, így bizonyos függvények (például document.write) nem mindig használhatóak markup bannerekbe kerülő kódban. Csak olyan oldalak esetében melyek az új, document.write-ot támogató, beépítést alkalmazzák, mind a document.write, mind a DOM Ready eseményre való csatlakozás elérhető!

  * A tagokat mindig le kell zárni, pl.: <br />
  * Minden ''&'' karaktert le kell cserélni ''&amp;''-ra, ami nem ''CDATA''-ba van csomagolva.
  * A scriptek és style tagok tartalmát egy ''CDATA'' tagbe érdemes helyezni, hogy ne kelljen lecserélni minden karaktert, ami amúgy foglalt, pl.: ''<'', ''>'', ''&''.

<code html>
<script type=”text/javascript”>
//<![CDATA[
    /*...*/
//]]>
</script>
</code>

<code html>
<style type=”text/css”>
!<![CDATA[
    !...
!]]>
</style>
</code>

  * Ezeken kívül minden image tag-nek rendelkeznie kell az alt attribútummal, még ha csak üres string is:

<code html>
<img alt=”” src=”[file:fáljnév.kiterjesztés]”></img>
</code>

:!: **Az alább írtakra akkor van szükség, ha a hagyományos Goa3 beépítést alkalmazzák, míg a document.write-ot támogató beépítésnél ezt nem kell követni.**

Fel kell készíteni a kreatívot arra, hogy a beépítés során a goa3 script felépíti a DOM elemeket JavaScript-tel, így ha például egy külső kód betöltése script tag beillesztésével történik, a script később fog megérkezni, mert a bekérés csak az eleme létrehozásakor indul el. Ez okozhat olyan hibát futás során, hogy egy kisebb script, ami például az animációkat indítja el, előbb áll majd rendelkezésre, mint mondjuk egy esetleges js library, például jQuery.

A megoldás erre a problémára egy olyan script használata, mely ciklikusan ellenőrzi a szükséges elemek meglétét, és csak miután minden rendelkezésre áll, kezdi el futtatni a kreatívot. Ezt a script-et érdemes a banner kód végére rakni.

<code javascript>
(function () {
    var started = false,
        timer,
        neededElement = undefined,

        adStarter = function() {
        
            if (started) return;

            neededElement = window.$;
            if (neededElement) {

                banner.init();

                started = true;
                clearTimeout(timer);
                return;
            }

            timer = setTimeout(adStarter, 100);
        };

    adStarter();
})();
</code>

Esetleg egy elem meglétét is vizsgálnunk kell:

<code javascript>
neededElement = window.$ && $('myDiv')[0];
</code>

----

===== Használható változók =====

^ Változó neve      ^ Értéke                               ^
| [statichost]      | Az aktuális statikus fájlkiszolgáló  |
| [location]        | A banner helye teljes URL-lel        |
| [target]          | A cél ablak                          |
| [timestamp]       | Aktuális idő                         |
| [referer]         | A referer oldal címe                 |
| [cthref]          | A CT URL                             |
| [zone]            | Zóna azonosító                       |
| [goal]            | Goal (terv) azonosító           |
| [banner]          | Banner azonosító                     |
| [ord]             | Page impression ID                   |
| [imgpre]          | A banner helye teljes URL-lel        |
| [zona]            | Zóna azonosító                       |

----

===== Display sablonok funkcióinak használata =====

A goa3 beépítési kódban a különböző extra beépítési módok úgy vannak megoldva, hogy mindegyiket egy külön javascript osztály végzi. Ezeket a megjelenést intéző javascript-eket display sablonoknak nevezzük.

A publikus displayekkel megjelenő példa bannereket és paraméterezésüket ezen az oldalon lehet megnézni és a paraméterek értékeit módosítva tesztelni.

Egyedi, privát display sablonokat az Adverticum ügyfelei is fejleszthetnek maguknak, az erről szóló dokumentációt itt olvashat: 

Több display típus is igényel interakciót a kreatív és a display között. Ilyenek például a kinyíló display-ek (sidekick, multi-expand, slider, stb.). Ilyen esetben ki kell adnunk a kinyíló és bezáró parancsokat. Ehhez annyit kell csak tenni, hogy a kampánymenedzserrel egyeztetjük a nyitó és záró függvények nevét, hogy ugyanazt adja meg a kampánymenedzser az adminfelületen, mint ami a kódunkban szerepel. 

=== Fontos tudnivalók! ===

  * HTML bannerként futtatott kreatív esetén, a Sidekick ill. Slider display-ek másodlagos kreatívjai, hogy bezárhatóak legyenek a kreatívba ágyazott gomb segítségével, el kell kérnünk az elsődleges banner zóna azonosítóját, mert csak ennek ismeretében fog kódunk működni. Ez esetben a példakódokban használt ''[zone]'' változó helyett a zónaazonosítót hardcode-olnunk kell!
  * HTML bannerként futtatott kreatív esetén a nyitva indulást nem lehet lekérdezni. Ebben az esetben a kreatív dolga kezelni, az olyan igényeket, hogy naponta egyszer induljon nyitva.
==== A Display sablonok elérhető funkciói ====

^ Display neve az adminon      ^ Display kódneve a válaszban      ^   open    ^   hide    ^   close    ^
| Billboard                    | billboard                        | x         |           | x          |
| Layer (csak Goa3)            | customLayer                      |           |           | x          |
| Beágyazott                   | embedded                         |           |           |            |
| Filmstrip                    | filmstrip                        |           |           |            |
| Interstitial                 | interstitial                     |           |           | x          |
| Preroll/postroll             | movieClip                        |           |           | x          |
| Méretet változtató           | multiExpand                      | x         |           | x          |
| Szamárfül                    | peel                             | x         |           | x          |
| Scroll                       | scroll                           |           |           | x          |
| Sidekick                     | sidekick                         | x         | x         | x          |
| Lebegő felhőkarcoló          | skyscraper                       |           |           | x          |
| Csúszó                       | slider                           | x         | x         | x          |
| Böngésző ablakhoz ragadó     | sticky                           |           |           | x          |
| Úszó                         | swimmer                          |           |           | x          |
| Full page flex               | fullPage                         |           |           | x          |
| Mobil kombinált              | mobileCombo                      | x         | x         | x          |

==== HTML banner ====

=== Példa az onclick attribútum használatával ===

<code html>
<div onclick="(function(){window.top.postMessage('[zone].open', '*');})();">X</div>
</code>

=== Példa jQuery használatával ===

<code javascript>
$('exampleCloseButton').click(function () {
    window.top.postMessage('[zone].open', '*');
});
</code>

=== Nyitás ===

<code javascript>
window.top.postMessage('[zone].open', '*');
</code>

=== Zárás ===

<code javascript>
window.top.postMessage('[zone].close', '*');
</code>

=== Elrejtés ===

<code javascript>
window.top.postMessage('[zone].hide', '*');
</code>
==== Markup banner ====

=== Példa az onclick attribútum használatával ===

<code html>
<div onclick="(function(){goAdverticum3.getZone([zone]).open();})();">X</div>
</code>

=== Példa jQuery használatával ===

<code javascript>
  $('exampleCloseButton').click(function () {
    goAdverticum3.getZone([zone]).open();
  });
</code>

=== Nyitás ===

<code javascript>
goAdverticum3.getZone([zone]).open();
</code>

=== Zárás ===

<code javascript>
goAdverticum3.getZone([zone]).close();
</code>

=== Elrejtés ===

<code javascript>
goAdverticum3.getZone([zone]).hide();
</code>

=== Nyitva indulás vizsgálata ===

<code javascript>
if (goAdverticum3.getZone([zone]).openNow) {    
/*...*/
}
</code>

----

===== Banneren belüli események mérése tracking linkkel =====

:!: **Figyelem! A HTML bannert az AdServer iframe-ben jeleníti meg, így Markup bannerekre az itt írtak nem alkalmazhatóak. Az itt megadott linkeket egy iframe-ben megjelenítve végezhető el a mérés a Markup bannerek esetén.**
  
A HTML bannerekben megoldható egyes eseményeknek (például a nem cél oldalra vivő kattintásoknak, vagy a tabok használatának) nyomonkövetése is, speciális tracking URL-ek segítségével. A tracking URL-eket és azt az információt, hogy melyik tracking URL-nek melyik eseményt kell mérnie, a kampánymenedzsertől kapja a bannerkészítő. (Ezeket a kampánymenedzsernek külön mérőkampányba érdemes felvennie.)

:!: ** Figyelem! Az adminfelületen felvehető és az alábbi módon referálható URL-ek beleszámítanak a banner CT adataiba, így trackingre nem ezeket, hanem a tracking linkek direkt beépítését ajánljuk!**

A tracking URL-ek használatával gyakorlatilag minden olyan esemény mérhetővé tehető, ami egy jelzést küld az esemény bekövetkeztekor. A leggyakoribb ilyen a kattintás esemény, de ilyen lehet a mouse over esemény is. Ellenpélda a mouse move esemény, mivel az egér mozgatása folyamatos jelzéseket jelent, és nem mérhető ezzel az egér tartózkodási ideje sem egy adott mező felett.

Az események mérése javascripttel:
<code javascript>

window.goAdverticum3.onReady(function( goa3 ) {

    var $ = goa3jQuery;

    $('#button').click(function ( goa3 ) {
	$.get('http://ad.adverticum.net/t/?z=2084028&g=2084026&b=208402400&h=[LOCATION]&p=[PAGEIID]');
    });
});
</code>

----

===== Bannerek eseményeinek mérése az új statisztika rendszerben =====

Az új statisztika rendszerben van arra lehetőség, hogy az eddig megszokott méréseken (banner megjelenés, kattintás) felül az elért internetezők különböző akcióit is mérni tudjuk. Ehhez többféle mérési pontot biztosítunk. Ezek segítségével a kreatívok fejlesztői felkészíthetik bannereiket az új statisztika rendszer ezen lehetőségeinek kiaknázására.

A támogatott display-ekben elérhető események (nyitás, bezárás stb.) automatikusan mérődnek is. Ezekben az esetekben a mérőpontok kezelését a display automatikusan végzi.

:!: **Figyelem! A display-ekben csak a felhasználó által kezdeményezett akciókat mérjük, az automata kinyílást illetve bezáródást nem!**

Az összegyűjtött adatokat a rendszer egy ideig tárolja/gyűjti, majd a ciklikus adatküldő juttatja el szervereink felé. Ez 3 másodpercenként történik, amennyiben van küldendő adat, és a böngészőablak is fókuszban van. Ezzel minimalizálható az adatvesztés, de az adatforgalom is jóval csekélyebb, mintha minden mérést egyből küldenénk.

A különböző banner típusokban (HTML,stb.) különbözőképpen kell meghívni a mérőpontokat. Ezekre mutatunk egy-egy példát lentebb. A bannerhez rendelt mérőpontokat a zónán keresztül lehet elérni, a fentebb bemutatott ''.getZone()'' függvény segítségével.

Azt, hogy egy mérőpontot hányszor lehet meghívni egy banner letöltésen belül, lehet korlátozni, ami azt jelenti, hogy például bannerenként maximum 5 nyitásig számoljon a rendszer egy oldalletöltésen belül, mert a túlzott adatgyűjtés az információmennyiség rovására mehet.

A mérőpontok rendelkezhetnek minimum és maximum határértékekkel is, amikről részletesen írunk az egyes mérés típusok kifejtésénél. Beállítható, hogy a rendszer miként kezelje a maximum értékek túllépését, vagy ha a minimum értéket nem érte el a mérés. Jelenleg két működés alkalmazható mindkét esetben. A maximális érték esetén beállítható, hogy ha a mérés túllépné a maximális korlátot, a rendszer eldobja a mérést, vagy hogy "levágja" az értéket, hogy az ne legyen nagyobb a maximumnál. Ugyan így a minimumot el nem érő méréseket is figyelmen kívül hagyhatjuk, vagy felkerekíttethetjük a rendszerrel.

Az oldal frissítése után a banner újratöltődik, és ilyenkor a határértékeket ismét nulláról kezdjük számolni, mivel az újratöltött banner már egy új mérőpont lesz. 

==== Egyszerű mérő ====

Az egyszerű mérőpont minden hívására a rendszer logol egyet.

==Határértéke:==
  * Maximális meghívhatóság

=== HTML banner esetén ===

Példánkban a videó indítását jelezzük. Ehhez pedig a 'play' mérőt használjuk.

<code javascript>
window.top.postMessage('[zone].measure.play.fire', '*');
</code>

=== Markup banner esetén ===

A példában szereplő 'play' egyszerű esemény mérő felépítése, mely a zóna adatainak lekérése után az alábbi felépítés alapján érhető el.

<code javascript>
{
    0000000: {
 
        displayed: {Boolean},
        ...
        node: {Object},

        measures: {
            play: {
                fire: function () {...}
            }
        }
    }
}
</code>

Példánkban a videó indítását jelezzük. Ehhez pedig a 'play' mérőt használjuk.

<code javascript>
goAdverticum3.getZone([zone]).measure.play.fire();

</code>

==== Időmérő ====

Az időmérővel egy kezdő (start) és egy vég (stop) esemény közötti időt lehet mérni. Lényegében úgy működik, mint egy stopperóra. Amennyiben egy mérés már folyamatban van, és újabb ''start()'' utasítást kap a rendszer, az előző mérést leállítja, elküldi a mérést, és egy újat indít el. Lényegében az történik, mintha meghívtuk volna a ''stop()'' funkciót, majd rögtön utána a ''start()''-ot.

==Határértékei:==
  * Maximális meghívhatóság
  * Minimálisan mérhető idő
  * Maximálisan mérhető idő

=== HTML banner esetén ===

Példánkban egy banner nyitott állapotban töltött idejét mérjük. Ehhez az 'Time' mérőt használjuk. 

Időmérés kezdete:
<code javascript>
// Küldünk egy üzenetet a legfelső, a Goa3-at futattó window-nak, majd jelezzük
// a meghívandó mérőt.
window.top.postMessage('[zone].measure.Time.start', '*');
</code>

Időmérés vége:

<code javascript>
// Küldünk egy üzenetet a legfelső, a Goa3-at futattó window-nak, majd jelezzük
// a meghívandó mérőt.
window.top.postMessage('[zone].measure.Time.stop', '*');
</code>

=== Markup banner esetén ===

A példában szereplő 'Time' időmérő felépítése, a zóna adatainak lekérése után az alábbi formában érhető el.

<code javascript>

{
    0000000: { // A zóna ID a kulcs, és a zónának van tartalma.
 
        displayed: {Boolean},
        ...
        node: {Object},
 
        measures: {
            Time: {
                start: function () {...},
                stop: function () {...},
            }
        }
    }
}
</code>

Példánkban egy banner nyitott állapotban töltött idejét mérjük. Ehhez az 'Time' mérőt használjuk.

Időmérés kezdete:
<code javascript>
// Elindítjuk az időmérést.
goAdverticum3.getZone([zone]).measure.Time.start();
</code>

Időmérés vége:

<code javascript>
// Leállítjuk az időmérést.
goAdverticum3.getZone([zone]).measure.Time.stop();
</code>
==== Mennyiségmérő ====

A mennyiségmérőkkel lehetőség nyílik összesített eredményeket küldeni a rendszernek. Az egyszerű mérővel szemben itt a funkció paramétereként elküldhetünk egy számot, melyet mindenképpen pozitív egész (''int'') számmá alakít a rendszer!

==Határértékei:==
  * Maximális meghívhatóság
  * Minimálisan mérhető mennyiség
  * Maximálisan mérhető mennyiség

=== HTML banner esetén ===

Példánkban egy buborékpusztító játék ereményét mérjük. Ehhez pedig a 'bubbles' mérőt használjuk.

<code javascript>
// Küldünk egy üzenetet a legfelső, a Goa3-at futattó window-nak, majd jelezzük
// a meghívandó mérőt, és zárójelben az értéket.
window.top.postMessage('[zone].measure.bubbles.fire(5)', '*');
</code>


=== Markup banner esetén ===

A példában szereplő 'bubbles' mennyiségmérő felépítése a zóna adatainak lekérése után az alábbi formában érhető el.

<code javascript>

{
    0000000: { // A zóna ID a kulcs, és a zónának van tartalma.
 
        displayed: {Boolean},
        ...
        node: {Object},
 
        measures: {
            bubbles: {
                fire: function ( value ) {...} 
            }
        }
    }
}
</code>

Példánkban egy buborékpusztító játék ereményét mérjük. Ehhez pedig a 'bubbles' mérőt használjuk.

<code javascript>
// Egyszerűen elsütjük az eseményt.
goAdverticum3.getZone([zone]).measure.bubbles.fire(5);
</code>

----

===== Goa3 eseménykezelő =====

Választható események:

  * open - A display nyitásakor
  * close - A display bezárásakor
  * remove - Bizonyos display-ek esetén a banner eltüntetésekor
  * viewable - Mikor a zóna képernyőre kerül, azaz legalább 50%-a legalább 1mp-ig látható, kitakarástól függetlenül
  * invoke - A zóna megjelenítésekor sül el, lényegében az onGoa3Invocation-höz hasonló, de az átadott adatok eltérőek.

====Goa3 események használata====

Az eseményekre háromféleképpen lehet feliratkozni.

**1. Az első eset, mikor a Goa3 referenciáját használjuk alapnak**, így minden bekövetkező eseményről értesülhetünk.

<code javascript>

window.goAdverticum3.onReady(function( goa3 ) {

	goa3.on('viewable', function ( jQueryEvent, goa3Event ) {
		window.console.log(goa3Event);
	});
});
</code>

A paraméterek közt elsőként a jQuery Event objektuma kapható meg, majd ezt követi a Goa3 által összeállított adatcsomag. A fenti funkció futtatása után a következő objektumot láthatjuk a konzolban

<code javascript>
{
    type: "viewable",
    zone: {

        id: 1785138,

        displayName: "embedded",
        displayParams: {...},
        
        displayed: true,
        
        width: 250
        height: 250,

        node: jQuery.fn.jQuery.init[1],

        on: function(ev, func) {...},
    }
}
</code>

**2. Alternatíva lehet az egyedi zónára való feliratkozás**, ami a kreatív készítőknek jelenthet könnyebbséget. Ezzel kivitelezhető lehet például egy olyan kreatív, mely csak akkor kezdi el az animációját, mikor képernyőre kerül. Ez Markup esetében működhet.

<code javascript>
goAdverticum3.getZone([zone]).on('viewable', function ( jQueryEvent, goa3Event ) {
    goa3Event.zone.open();
});
</code>

====Az elérhető események display típusonként====

A lenti táblázatban fel vannak tüntetve az egyes display típusonként használható események, köztük a ‘viewable’ és az ‘invoke’ események is, azonban ezeket a Goa3 globálisan végzi, így a bannertől ill. display-től függetlenül működnek.

A csillagozott esetek a következőket jelentik:

*: Ahol nemcsak ‘close’, hanem ‘remove’ esemény is szerepel, ott van mód a bannert ki és becsukni, és az alap kreatívot eltüntetni, egyébként minden más esetben a ‘close’ jelenti az eltüntetést.


| **Display neve az adminon**  | **Display kódneve a válaszban**  | **open**  | **close**  | **remove**  | **viewable**  | **invoke**  |
| Billboard                    | billboard                        | x         | x          |             | x             | x           |
| Layer (csak Goa3)            | customLayer                      |           | x          |             | x             | x           |
| Beágyazott                   | embedded                         |           |            |             | x             | x           |
| Filmstrip                    | filmstrip                        |           |            |             | x             | x           |
| Interstitial                 | interstitial                     |           | x          |             | x             | x           |
| Preroll/postroll             | movieClip                        |           | x          |             | x             | x           |
| Méretet változtató           | multiExpand                      | x         | x          |             | x             | x           |
| Szamárfül                    | peel                             | x         | x          |             | x             | x           |
| Scroll                       | scroll                           |           | x          |             | x             | x           |
| Sidekick                     | sidekick                         | x         | x          |             | x             | x           |
| Lebegő felhőkarcoló          | skyscraper                       |           | x          |             | x             | x           |
| Csúszó                       | slider                           | x         | x          | x*          | x             | x           |
| Böngésző ablakhoz ragadó     | sticky                           |           | x          |             | x             | x           |
| Úszó                         | swimmer                          |           | x          |             | x             | x           |
| Video Overlay                | videoOverlay                     | x         | x          |             | x             | x           |
| Full page flex               | fullPage                         |           | x          |             | x             | x           |
| Mobil kombinált              | mobileCombo                      | x         | x          | x*          | x             | x           |

----

=====További kivezetett funkciók=====

===.getZones( [zoneID] )===

A .getZones() a zónaadatok lekérését lehetővé tévő funkció. Ha a zoneID nincs definiálva, a teljes zónalistával tér vissza a függvény. Ebben az objektumban a kulcsok a zónák azonosítói (zoneID), értékük a zóna adatai. Ha megadjuk a zoneID paramétert (number vagy string típus), akkor az adott zóna szerepel a visszatérő adatokban. Amennyiben egy nem létező zónát kérünk, a válasz null. Tömbként több zónáról is kérhető adat, amiben az elemek zoneID-k (number vagy string formában), ekkor csak a lekért zónák fognak szerepelni a válaszban. 

:!: **Figyelem! A .getZones() függvényt külön script tagbe kell elhelyezni mint a .loadZones()-t, mert ellenkező esetben a válasz még nem érkezhet meg mikor ez végrehajtásra kerül, így a zónát üres zónának jelöli a rendszer.** :!:

<code javascript>
var zones = goAdverticum3.getZones();
console.log(zones);
</code>
==Paraméterek==

**zoneID** {Number|String|Array}: Nem kötelező

A keresett zóna ID-ja. 

==Visszatérő adatok==

A teljes zóna lista, ha a zoneID nincs definiálva.

<code javascript>
{
    0000000: { // A zóna ID a kulcs, és a zónának van tartalma.
 
        displayed: {Boolean}, // Azt jelzi, valamiképp beépítésre került-e a zóna.
        width: {Number}, // A banner szélessége, melyet megadtak az adminon.
        height: {Number}, // A banner magassága szintén az adminról.
        node: {Object} // Az a jQuery objektum, melybe az invokáció történt.
                       // Ha előtöltött, de be nem épített zónáról van szó, 
                       // akkor egy üres szülőtelen div-re mutat.
    },
    0000001: { // A zóna ID a kulcs, de üres.
 
        empty: true, // True, ha üres zónáról van szó. Ha nem üres, meg 
                     // sem kapja ezt az attribútumot.
        node: {Object} // Az a jQuery objektum, melybe az invokáció történt.
                       // Ha előtöltött, de be nem épített zónáról van szó, akkor 
                       // egy üres szülőtelen div-re mutat.
    }
}
</code>

Opcionális adatok, melyek csak bizonyos display-eknél szerepelnek.

<code javascript>

{
    openNow: {Boolean}, // Boolean érték, mely a banner nyitva indulásakor igaz,
                        // egyébként nem is szerepel.
    open: {Function},  // Ha van regisztrált nyitó funkció, innen ez meghívható.
    close: {Function}, // Ha van regisztrált záró funkció, innen ez meghívható.
    hide: {Function}, // Ha van regisztrált eltüntető funkció, innen ez meghívható.
}
</code>

Ha egy zoneID-t definiáltak, de az nem létező elem.

<code javascript>

null
</code>

===.getZone( zoneID )===

A függvény az adott zónára ad egy egyszerűbb lekérési módot főleg a kreatívok, illetve fejlesztőik részére. A getZones metódushoz hasonlóan itt is visszakaphatunk display-ektől függő, opcionális adatokat (pl: openNow, hide stb).

:!: **Figyelem! A .getZone() függvényt külön script tagbe kell elhelyezni mint a .loadZones()-t, mert ellenkező esetben a válasz még nem érkezhet meg mikor ez végrehajtásra kerül, így a zónát üres zónának jelöli a rendszer.** :!:

<code javascript>
var zone = goAdverticum3.getZone(1234567);
console.log(zone);
</code>
==Paraméterek==

**zoneID** {Number|String}

A keresett zóna ID-ja. 

==Visszatérő adatok==

Egy lekért zóna visszaérkező adatai.

<code javascript>

{
    id: {Number} // A zóna ID-je.
    displayed: {Boolean}, // Azt jelzi, valamiképp beépítésre került-e a zóna.
    width: {Number}, // A banner szélessége, melyet megadtak az adminon.
    height: {Number}, // A banner magassága szintén az adminról.
    node: {Object} // Az a jQuery objektum, melybe az invokáció történt.
}
</code>

----

===== Javaslatok CSS3 alapú responzív és animált bannerek elkészítéséhez =====

==== A mobilkészülékeken futó bannerek mérete ====

Mivel a kijelzők mérete készülékről-készülékre különbözhet, érdemes felkészítenünk a bannerünket erre. Mi a CSS3-ban használható ''@media'' tag használatát javasoljuk.

<code css>
@media screen and (max-width: 479px) {

  #[bannerID] {
    width: 320px;
    height: 50px;
  } 
}

@media all and (min-width: 480px){

  #[bannerID] {
    width: 480px;
    height: 120px;
  } 
}
</code>

Ez azt fogja eredményezni, hogy azon a készüléken, vagy a készülék azon állapotában, ahol a képernyő mérete kisebb, mint ''480px'', ott a ''320x50''-es bannerváltozat jelenjen meg. Azon a kijelzőn/állapotban ahol pedig 480px vagy annál nagyobb a képernyő szélessége, a ''480x120''-as hirdetés legyen látható.

Az alábbi kód ezzel szemben arról gondoskodik, hogy álló helyzetű készülék esetén az álló stílus legyen éle, fekvő helyzetű készülék esetén pedig a fekvő. Ezt akkor érdemes használni, ha az adott hirdetést képernyőméretre targetálva futtatjuk. Fontos, hogy az olyan tulajdonságok, melyek a készülék helyzetétől függenek, csak ezeken a ''@media'' tageken belül legyenek, mert ha ezen kívül definiáljuk őket, a kint lévők felülírják majd a belül lévőket minden esetben!

<code css>
@media all and (orientation: portrait) {

  #[bannerID] {
    width: 320px;
    height: 50px;
  } 
}

@media all and (orientation: landscape){

  #[bannerID] {
    width: 480px;
    height: 120px;
  } 
}

</code>

==== A banner átméretezése különböző képernyőméretek esetén ====

Az alábbi script egy megoldási javaslat, ha önmagát átméretező bannert szeretnénk csinálni, ami a képernyő állapotát figyelve – fektetett vagy állított – futtatja a megadott animációkat és/vagy méretezi át az egyes elemeket.

Felkészítjük bannerünket, hogy ha a képernyő felbontása kisebb mint ''480px'', ami egy gyakori fektetett szélesség, akkor az állított kijelzőre tervezett animáció fusson. Ha ''480'' pixelnél nagyobb a képernyő, akkor a képernyő magassága és szélessége alapján következtetjük ki, hogy milyen állapotban van a készülék.

A ''bigAnimation()'' és ''smallAnimation()'' függvények neve magáért beszél, de érdemes a stílusokat is változtatni az elemek mérete miatt, és kiinduló állapotba helyezni a kreatív elemeit.

<code javascript>

var currentOrientation,
    previousOrientation,
    checkOrientation = function () {

        if (window.innerWidth < 480) {
            currentOrientation = 'portrait';
        } else if (window.innerWidth > window.innerHeight) {
            currentOrientation = 'landscape';
        } else {
            currentOrientation = 'portrait';
        }

        if (previousOrientation === currentOrientation) return;
        else {

            if (currentOrientation === 'portrait') smallAnimation();
            else {
                bigAnimation();
            }
        }
        previousOrientation = currentOrientation;
    };

// Csatoljuk az eseménykezelőhöz a figyelő scriptünket.
window.addEventListener('resize', function () {
    checkOrientation();
}, false);

// Egyszer lefuttatjuk, mert az első megjelenésnél nem fut le az ablak átméreteződési esemény.
checkOrientation();
</code>

==== A mobilkészülékeken futó bannerek animációja ====

Androidra és iPhone-ra szánt reklámok esetén ''@webkit-keyframes'' nyújt könnyen kivitelezhető, és külön méretre szabható eszközöket. Fontos, az ''@webkit-keyframes'' Safari, Chrome és egyébb webkit alapú böngészőkben működik. Egyébb lehetőségek pl.: ''@ms-keyframes'' - Internet Explorerhez, ''@moz-keyframes'' - Mozillához. Ugyanígy a webkitet az alábbi kódokban lecserélve a megfelelő tagre felkészíthetjük a bannerünket a többi böngészőre is. Fontos tudni, hogy a különböző böngészők különböző módokon kezelhetik az animációkat, ezért ennek érdemes utánanézni, majd a különböző böngészőben letesztelni a bannert.

<code css>
@webkit - keyframes[animációID] {

    0% {
        opacity: 0;
    }

    50% {
        opacity: 1;
    }

    100% {
        opacity: 0;
    }
}
</code>

A százalékban az animáció százaléka értendő, bele a változtatott tulajdonság-érték pár.

<code css>
#[bannerID] {

    -webkit-animation-name: [animációID];
    -webkit-duration: [mp];
    -webkit-iteration-count: [int, infinite];
}
</code>

Az itt felsorolt opciók csak a jéghegy csúcsát jelentik. A teljesség igénye nélkül, csak a legfontosabb animációval kapcsolatos tippeket soroltuk fel. További praktikák és tanácsok széles tárháza itt található: http://css-tricks.com

Mivel az IEMobile hadilábon áll a CSS3-mal, a következő példából indulhatunk ki, ha olyan tartalmat szeretnénk megjeleníteni, ami csak IEMobile alatt szeretnénk, hogy megjelenjen. Ezt a kódot használhatjuk a HTML-ben (Windows Phone 7-nél korábbi készülékeken nem garantált a működés):

<code html>

<!--[ifIEMobile]>

…IE specifikus tartalom ide…

<![endif]-->

<!--[if!IEMobile]>

…Amit szeretnénk, hogy az IE figyelmen kívül hagyjon ide…

<![endif]-->
</code>

==== A bannerek feltöltése az AdServerbe ====

A bannerek feltöltéséről szóló felhasználói útmutatónkat az AdServer hozzáféréssel rendelkező felhasználóink az AdServernél is használt e-mail cím/jelszó párosukkal bejelentkezve az alábbi linkeken olvashatják:

https://support.adverticum.net/index.php?/Sales/Knowledgebase/Article/View/74/2/relatv-hivatkozst-tartalmaz-html-banner-felvitele

https://support.adverticum.net/index.php?/Sales/Knowledgebase/Article/View/130/2/markup-xhtml-banner-ltrehozsa

==== Példák ====

Mobilra szánt példabanner, mely banner átméretezését szemlélteti

Készítettünk egy egyszerű példa bannert, aminek az AdServeren keresztüli működését az alábbi linkeken demonstráljuk

Asztali számítógépen itt tekintse meg.

Desktop böngészőjében erre a linkre kattintva megtekintheti, hogy hogyan jelenik meg a banner egy álló és egy fekvő helyzetű készülék képernyőjén

https://support.adverticum.net/examples/html5markup/ip.html

Mobil készülékének böngészőjébe az alábbi rövidített URL-t beírva vagy a QR kódot beolvasva a saját készülékén is megnézheti a példa banner működését

http://bit.ly/Pjf5Ik

{{ :creatives:qr_ko_d.png?nolink&300 |}}

A banner forráskódja az alábbi linken érhető el:

https://support.adverticum.net/examples/html5markup/source.html

----

===== Mobil kombinált display =====

{{ :creatives:mobil_kombi_uj.png?nolink&600 |}}

==== Bázis kreatív ====

Mérete ''320x50''px ''320x480''-as kijelző esetén, vagy ''480x50''px, ha ezen kijelző fektetve van. Mivel a képernyő mérete dinamikusan változhat, erre a kreatívot is fell kell készíteni, ami CSS3 segítségével könnyen megoldható.

A bázis kreatív két részből áll. Egy nyitó és egy záró felületből. Erre egy nagyon egyszerű példák, alább.

:!: Figyelem, a class nevek megválasztásánál arra kell törekedni, hogy véletlenül se legyen ütközés azon oldal elemeinek class neveivel! **Ezen példában egyszerű általános neveket használunk, amelyek nem ajánlottak éles működés esetén.** A két felület egymás mellett helyezkedik el úgy, hogy mindig a megfelelő - nyitó vagy a záró felület - látható, a másik kikerül a látható képből. Tehát a valóságban a fentebb említett példa felbontás esetén, ez egy ''620x50''px-es, vagy egy ''840x50''px-es felület lesz. A nyitó felület a bal fele, a záró a jobb minden nyitó mód esetén!

=== Példa dinamikus méretek segítségével ===

Olyan HTML5 banner esetén, ahol az elemek animálódnak, illetve dinamikusan méreteződnek át, az alábbi kód ajánlott.

<code html>

<div class="wrapper">

    <div class="banner">
        ... A nyitó felület tartalma ... 
    </div>

    <div class="banner">
        ... A záró felület tartalma ...
    </div>
</div>

</code>

A CSS a következőképpen néz ki. Ez azt fogja eredményezni, hogy a nyitó felület piros, a záró felület zöld lesz, a könnyebb láthatóság kedvéért. A '.banner' a nyitó és záró felület közös tulajdonságaira vonatkozik, még a két felület különböző tulajdonságait a ''.banner:nth-child(odd)'' (a bal/nyitó oldal) és a ''.banner:nth-child(even)'' (a jobb/záró oldal) selectorokkal érjük el.

<code css>

.wrapper {

    position: absolute;

    width: 200%;
    height: 50px;
}

.banner {

    position: relative;
    overflow: hidden;
    float: left;

    width: 50%;
    height: 50px;
}

.banner:nth-child(odd) {
    background-color: #f00;
}

.banner:nth-child(even) {
    background-color: #0f0;
}
</code>

=== Példa fix méretek segítségével ===

Olyan banner esetén, ahol egy kép a nyitó illetve záró felület ezen kód ajánlott. Itt két képre van szükség, amit a banner a képernyő helyzete alapján megjelenít, a már fentebb említett méretekben.

<code html>

<div class="wrapper">

    <div class="portrait">
        ... Állított tartalom ...
    </div>
    <div class="landscape">
        ... Fektetett tartalom ...
    </div>
</div>

</code>

A hozzá tartozó CSS a következő, ami a képernyő helyzete alapján, az adekvát elemet jeleníti meg, a class nevek magukért beszélnek.

<code css>

.banner {

    position: relative;
    float: left;
    overflow: hidden;

    width: 50%;
    height: 50px;
}

.portrait {

    width: 320px;
    height: 50px;
}

.landscape {

    width: 480px;
    height: 50px;
}

@media only screen and (orientation: portrait) {

    .portrait {
        display: block;
    }

    .landscape {
        display: none;
    }
}

@media only screen and (orientation: landscape) {

    .portrait {
        display: none;
    }

    .landscape {
        display: block;
    }
}

</code>

==== Teljes oldalas kreatív ====

Ez a látható képernyőfelület fennmaradó részét tölti ki. Androidos készüléken a beépített böngészőn, ''320x480''-as kijelző esetén állított állapotban ''320x430''px méretű lesz. Tehát a teljes rendelkezésre álló felület szélessége, és a rendelkezésre álló magasság, amiből kivonjuk a bázis kreatív magasságát.

Ezen kód egy halvány piros háttér előtt jeleníti meg a fektetett vagy állított tartalmat. Jelenleg csak egy szöveg van benne, de ez lehet szinte akármilyen bonyolultságú HTML5 vagy akár csak két kép, egy az állított állapothoz, egy pedig a fektetetthez.

<code html>

<div id="fullPage">

    <div class="title port">
        ... Állított tartalom ...
    </div>

    <div class="title land">
        ... Fektetett tartalom ...
    </div>

</div>

</code>

A hozzá tartozó CSS.

<code css>

#fullPage {

    position: absolute;

    height: 100%;
    width: 100%;
    background-color: #faa;
}

.title {

    width: 100px;
    margin: 20px auto;

    text-align: center;
    color: #000;
}

@media only screen and (orientation: portrait) {

    .port {
        display: block;
    }

    .land {
        display: none;
    }
}

@media only screen and (orientation: landscape) {

    .port {
        display: none;
    }

    .land {
        display: block;
    }
}

</code>