Ad Alliance Tag Control Anbindung

Allgemeines

Die AdAlliance stellt eine JavaScript-Schnittstelle zur Verfügung, welche Methoden definiert, mit Hilfe derer Aufrufe des AdAlliance Ad Servers konfiguriert werden. Die Schnittstelle ist in einem eigenen Namensraum definiert: MoltenBundle.

Der Schnittstellen-Code wird für jede Website dynamisch aus der Tag Control von der AdAlliance generiert. Die Tag Control erlaubt es der AdAlliance, Änderungen an der Konfiguration für die Werbeeinbindung vorzunehmen und diese zeitnah und ohne Eingreifen des Publishers live zu stellen. So kann bei korrekter Einbindung beispielsweise innerhalb von fünf Minuten die gesamte Werbeausspielung per Knopfdruck geändert oder ein bestimmter Werbeplatz unterdrückt werden.

MoltenBundle.js

Enthält eine JSON-Konfiguration, alle Methoden der Tag Control, sowie einen site-individuellen JavaScript-Teil, in dem z.B. Callbacks definiert werden.

Hosting der Schnittstelle

Die AdAlliance stellt für jede Webseite individuelle URLs zur Verfügung. Über diese erfolgt dann jeweils auf sogenannten Satelliten der Abruf der Preview- und Produktiv-Version der MoltenBundle.js / MoltenBundle.bottom.js.

Beispiel:

https://adctrl.emsmobile.de/molten/live/[sitename]/MoltenBundle.bottom.js

https://adctrl.emsmobile.de/molten/preview/[sitename]/MoltenBundle.bottom.js

https://adctrl.emsmobile.de/molten/live/[sitename]/MoltenBundle.top.js

https://adctrl.emsmobile.de/molten/preview/[sitename]/MoltenBundle.top.js 

Die Satelliten eignen sich nicht für hochvolumige Zugriffe!

Sie sind einzig für die Abholung durch externe, zeitgesteuerte Methoden konfiguriert. Aus diesem Grund wird nur die Preview URLs in der Seite implementiert. Die Live URLs für top.js und bottom.js liegt auf einem Contentserver der Seite und kann dann beispielsweise per CRON-Job unter Nutzung von wget oder curl abgerufen werden. Als Zeitintervall werden 5min empfohlen.

Ad Integration - Initialisierung des MoltenBundle – bottom.js (ex GuJAd)

Die Einbindung der Schnittstelle erfolgt im Normalfall voll asynchron, d.h. sowohl das initiale Skript als auch die Aufrufe des Ad Servers erfolgen mit asynchroner Client-Server-Kommunikation.

Elemente im <head>-Block der Site

1

2

3

4

5

6

7

8

9

10

  varMoltenBundle = MoltenBundle || {};

    MoltenBundle.cmd = MoltenBundle.cmd || [];

        MoltenBundle.cmd.push(function() {

            MoltenBundle.getClient().setSiteType('desktop, mobile or tablet');

            MoltenBundle.getClient().setZone('zonename');

            MoltenBundle.getClient().setIsIndexPage(true| false);

            MoltenBundle.getClient().setKeywords(['keyword1','keyword2','keyword3']); 

    });

</script>

**Keywords are optional**

Die Site-URL wird zu dem auf das Vorhandensein des Parameters „ada=1“ geprüft. Ist dieser vorhanden, ruft die Site die Schnittstelle vom Preview- statt vom Live-System ab.

Es wird die CSS-Datei geladen sowie die sogenannte “command queue” initialisiert. In dieser Warteschlange werden alle Schnittstellenmethoden-Aufrufe gesammelt, bis die Schnittstelle vollständig geladen wurde. Es wird die JavaScript-Datei geladen. Dieser <script>-Block sollte ganz am Ende des <body>-Blocks der Site eingebunden werden.

Elemente im <body>-Block der Site 

1

2

3

4

5

6

7

8

9

10

    !(function(){

         vars = document.createElement('script');

         s.type = 'text/javascript';

         s.async = 'true';

         s.src = (window.location.search.indexOf('ada=1') > -1) ?

                 'Preview – URL': 'Live - URL';

                 document.body.appendChild(s);

         })();

</script>

 Ad Integration - Initialisierung des MoltenBundle – top.js (ex VDC)

Die URL https://bilder-a.akamaihd.net/ip/js/ipdvdc/ipdvdc.min.js muss durch den internen Pfad zur MoltenBundle.top.js ersetzt werden. Das Laden erfolgt weiterhin asynchron im Head der Seite.

https://adctrl.emsmobile.de/molten/live/[sitename]/MoltenBundle.top.js

https://adctrl.emsmobile.de/molten/preview/[sitename]/MoltenBundle.top.js 

Einbinden von Ads

Der Befehl zum Laden eines Ads befindet sich in einem Skriptblock innerhalb eines div-Containers mit einer eindeutigen ID. Die Funktion zum Laden nimmt dieselbe ID als Parameter entgegen. 

Code-Beispiel (nicht einsatzfähig)

if (MoltenBundle !== undefined && MoltenBundle.cmd !== undefined) {

MoltenBundle.cmd.push(function() {

MoltenBundle.push('halfpagead_1');

});

}

</script>

</div>

Der div-Container beinhaltet genau den Script-Tag, innerhalb dessen die Methode MoltenBundle.push() in die MoltenBundle Queue geschrieben wird, wobei der Bezeichner der Position als JavaScript-String übergeben wird.

Welche Bezeichner verwendet werden sollen, kann dem Briefing bzw. dem Vermarktungsgrid entnommen werden.

Beim Einsatz von HTML5 kann der div-Tag ohne Beeinträchtigung der Funktion durch andere semantisch sinnvollere Tags (z.B. figure) ersetzt werden.

Es wird empfohlen, sitespezifische div-Container („Wrapper“) um die vorbenannten Ad-Positionen zu legen. Diese können dann im Einzelnen positioniert werden.

Finalisierung der Ad-Integration

Am Ende der HTML-Seite (idealerweise direkt vor dem schließenden Body-Tag) muss noch ein Block eingefügt werden: 

1

2

3

4

5

6

7

8

9

          if(MoltenBundle !== undefined && MoltenBundle.cmd !== undefined) {

             MoltenBundle.cmd.push(function() {

               MoltenBundle.finalize();

             });

         }

      </script>

</div>

Testen der Implementierung

Zum Testen der Implementierung kann an eine Page-URL der Parameter “testZone” gehängt werden.Dadurch wird als Site-Konfiguration eine Test-Instanz verwendet. Beispielsweise enthält die Zone „develop“ dauerhaft Testschaltungen mit Platzhalter-Werbung. 

Vor dem Einbinden von Ads können Grundfunktionen angepasst und bestimmte Targetings gesetzt werden. Diese Methoden müssen nach der Initialisierung der „command queue“ aufgerufen werden. Die folgenden Methoden müssen vor dem ersten MoltenBundle.push Aufruf aufgerufen worden sein. Alle Aufrufe müssen bei Verwendung der voll asynchronen Anbindung in die Warteschlange geschrieben werden:

1

2

3

4

5

6

7

        if(MoltenBundle !== undefined && MoltenBundle.cmd !== undefined) {

            MoltenBundle.cmd.push(function() {

                <Methoden-Aufruf>;

            });

        }

</script>

addKeyword(s):

Mit diesen Funktionen können Elemente einer Verschlagwortung zwecks besseren Targetings an den Ad Server übergeben werden. Setzen aller Keywords mit einem Array:

1	MoltenBundle.getClient().setKeywords(['apfel', 'kirsche', 'zimt']);

 Ergänzen der Keywords um ein weiteres:

1	MoltenBundle.getClient().addKeyword('banane');

 Ergänzen der Keywords um weitere:

1	MoltenBundle.getClient().addKeywords(['kiwi', 'sahne']);

 

addTargetingParameter:

Mit dieser Methode ist es möglich, Custom Targeting Parameter zu übergeben.

1	MoltenBundle.getClient().addTargetingParameter('alter','43');

Unterdrücken von Werbung

Es gibt verschiedenen Variationen, die dazu führen, dass bestimmte Werbeformen nicht erscheinen sollen.

Werbefreie Page

Es gibt innerhalb des AdAllianceAdTag Management Systems eine Zone mit dem Namen „_noad“, in der alle Werbeplätze abgeschaltet sind:

1	MoltenBundle.getClient().setZone(‘_noad’);

Deaktivieren einer bestimmten Werbeform

Mit dem Ziel ein bestimmtes Ad nicht in die aktuelle Seite zu laden:

1	MoltenBundle.getClient().disableAdPosition(‘superbanner_1’);

Bad News

Unter Umständen sind schlechte Nachrichten und Werbung nicht vereinbar. Hierfür gibt es einen Methodenaufruf, der das AdAllianceAdTag Management System veranlasst, keinen Ad-Call auszulösen:

1	MoltenBundle.getClient().setPageAsBadNews();

Bitte nutzen sie für das Deaktivieren von Werbung nur eine dieser Methoden. Andernfalls werden die Daten des Ad Server Analyse-Tools verfälscht, was im Angebotsprozess zu Fehlern führt.

Event Handler

Vor dem Einbinden eines Ads können Handler definiert werden, die auf Ladeereignisse reagieren:

registerBeforeInitialLoadHandler

Registriert eine Funktion, die zur Initialisierung ausgeführt wird: 

1

2

3

4

5

6

7

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerBeforeInitialLoadHandler(

            function(){

                    alert('hello');

            }

      );

});

 

registerBeforeLoadFirstPositionHandler

Registriert eine Funktion, die direkt vor dem ersten Ad Call ausgeführt wird: 

1

2

3

4

5

6

7

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerBeforeLoadFirstPositionHandler(

            function(){

                    alert('jetzt geht es los');

            }

      );

});

registerAllAdsLoadedHandler

Registriert eine Funktion, die nach dem letzten Ad Call ausgeführt wird. Dieser Handler bezeichnet nicht den Abschluss des Renderings, sondern des Ladens der Werbemittel vom AdServer: 

?

1

2

3

4

5

6

7

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerAllAdsLoadedHandler(

            function(){

                    alert('fertig!');

            }

      );

});  

registerBeforeAdreloadHandler

Registriert eine Funktion, die vor dem Neuladen von Werbung ausgeführt wird:

?

1

2

3

4

5

6

7

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerBeforeAdreloadHandler(

            function(){

                    alert('und von vorn');

            }

      );

});

registerBeforeLoadAdPositionHandler

Dieser Handler wird aufgerufen, bevor eine Werbeposition geladen wird. Als Parameter wird das aktuelle Positionsobjekt übergeben, welches Informationen über dieses enthält wie z.B. den Namen. Weitere Informationen zum Positionsobjekt erhalten Sie weiter unten:

1

2

3

4

5

MoltenBundle.cmd.push(function() {

          MoltenBundle.registerBeforeLoadAdPositionHandler(function(position) {

          // Funktionsinhalt

          });

registerAdPositionLoadedHandler

Dieser Handler wird aufgerufen, nach dem ein Ad-Slot geladen wurde. Als Parameter wird das aktuelle Positionsobjekt übergeben, welches Informationen über dieses enthält wie z.B. den Namen oder ob ein Ad enthalten ist. Weitere Informationen zum Positionsobjekt erhalten Sie weiter unten.Dieser Handler bezeichnet nicht den Abschluss des Renderings, sondern des Ladens der Werbemittel vom AdServer.

1

2

3

4

5

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerAdPositionLoadedHandler(function(position) {

      // Funktionsinhalt

      });

registerSplitQueueFinishedHandler

Dieser Handler wird aufgerufen, nachdem die zur SplitQueue zusammengefassten AdSlots geladen wurden. Diese sind in den meisten Fällen die Above-The-Fold Formate wie Wallpaper, Superbanner, Billboard, Skyscraper. 

1

2

3

4

5

MoltenBundle.cmd.push(function() {

      MoltenBundle.registerSplitQueueFinishedHandler(function() {

      // Funktionsinhalt

      });

Positionsobjekt:

Das Positionsobjekt liefert diverse Methoden, um die Antwort des AdServers genauer zu untersuchen. Die relevanten Methoden für Publisher auf dem Object sind:

getName(): liefert als String den Namen des AdSlots zurück, für den der Handler aufgerufen wurde. Etwa "superbanner_1"

containsAd(): liefert als boolean zurück, ob der AdSlot ein Werbemittel enthält oder nicht. Im Negativfall wird der AdSlot von der MoltenBundle ausgeblendet

getGPTEvent().size: GPTEvent liefert einen Großteil von Google-spezifischen Werten zurück. Am relevantesten ist das size-Array. Index 0 enthält die Breite, Index 1 die Höhe des ausgelieferten Werbemittels. Achtung: 728x600 bezeichnet das WallpaperAd. 

Ad Reload

Ein, einige oder alle Ads können neu geladen werden:

reloadAd

Lädt in das div-Element mit der als Parameter übergebenen ID ein neues Ad:

1

2

3

MoltenBundle.cmd.push(function() {

      MoltenBundle.getClient().reloadAd('superbanner_1');

});

reloadAds

Lädt alle Ads neu:

1

2

3

MoltenBundle.cmd.push(function() {

      MoltenBundle.getClient().reloadAds();

});

reloadSpecificAds

Lädt die im Array angegebenen Ads neu:

1

2

3

MoltenBundle.cmd.push(function() {

      MoltenBundle.getClient().reloadSpecificAds(['superbanner_1', 'rectangle_1']);

});

DSGVO

Im Rahmen der DSGVO stellen wir erweiterte Datenschutztexte zur Verfügung, die sie in ihr digitales Angebot einbinden wollen. Über diese können User des Angebots der Erhebung und Verarbeitung ihrer Daten zu personalisierten Werbediensten widersprechen. Haben Sie ein eigenes Privacy Center, in dem User diese Einstellung vornehmen können, so können sie ein OptIn/OptOut direkt über eine JavaScript Methode an uns übergeben: 

1	MoltenBundle.Privacy.isOptedOut()

Help Center

Ad Alliance Tag Control Anbindung

Allgemeines

Hosting der Schnittstelle

Ad Integration - Initialisierung des MoltenBundle – bottom.js (ex GuJAd)

Ad Integration - Initialisierung des MoltenBundle – top.js (ex VDC)

Einbinden von Ads

Finalisierung der Ad-Integration

Testen der Implementierung

Weitere Konfigurationsfunktionen

addKeyword(s):

addTargetingParameter:

Unterdrücken von Werbung

Werbefreie Page

Bad News

Event Handler

registerBeforeInitialLoadHandler

registerBeforeLoadFirstPositionHandler

registerAllAdsLoadedHandler

registerBeforeAdreloadHandler

registerBeforeLoadAdPositionHandler

registerAdPositionLoadedHandler

registerSplitQueueFinishedHandler

Ad Reload

DSGVO