Adcontroller
Implementierung AdController-Deployment (API + Konfiguration)
Allgemeine Informationen
Der AdController stellt in Form eines Script-Deployments ein Framework für die Initialisierung und das Rendering einer Anzeigenanforderung für die jeweils gültige Konfiguration einer Angebotsseite zur Verfügung.
Die Implementierung des Script-Deployments soll für die optimierte Bereitstellung der Dienstekonfiguration sowie Steuerbarkeit der prozessualen Code-Ausführung im <head>-Tag der Seite erfolgen. Das Script funktioniert zu 100% asynchron und verwendet keinen blockierenden Script-Code. Kann aus technischen Gründen nicht auf das <head>-Tag zugegriffen werden, ist eine Implementierung im Dokument-body noch vor dem erstem AdRequest zu prüfen (bitte stimmen Sie sich in diesem Fall gesondert mit iq digital ab). Die Initialisierung des AdControllers (AC) soll frühstmöglich erfolgen und ist Voraussetzung für die Anzeigeaufrufe (AdController.render-Aufrufe) zur Anzeigenanforderung. Sollte das nicht möglich sein bzw. Advertising-Technologien in Abhängigkeit von eintretenden Events (z.B. nach Page-Load) vorausgesetzt sein, stimmen Sie sich bitte gesondert mit iq digital ab.
Es sollte im Voraus geklärt werden, ob es sich bei Ihrem Angebot um eine klassische Webeanwendung handelt, die aus mehreren untereinander verlinkten HTML-Dokumenten besteht (d.h. bei initialem Aufruf einer Content-Seite sowie Navigation zu anderen Seiten wird auch immer ein Browser-Refresh ausgeführt). Sollten Sie im Rahmen einer "Single-Page-Webanwendung" ein davon abweichendes Konzept implementieren, sollten Sie zusätzlich die Schritte im Abschnitt Single Page Applikation (Kein Pageload) befolgen.
Wenn lediglich redaktionelle Elemente derselben Seite asynchron nachladen werden (z.B. Bildergalerien ohne Page-Refresh), bietet der AdController zu diesem Zweck eine Callback-Funktion zum Nachladen der Anzeigenpositionen an. Hier können die Schritte aus Abschnitt Single Page Applikation (Kein Pageload) ignoriert werden. Der Publisher verantwortet die Event-Bindung zum Triggern des Callback nach gemeinsamer Absprache mit iq digital ( siehe Abschnitt Callback-Funktion zum Nachladen der Anzeigenpositionen).
Hosting & Einbindung AdController
Es bestehen zwei Möglichkeiten für das Hosting/Einbindung des AdController Script-Deployments auf Ihren Seiten:
- Abruf des AC-Script-Deployments von einem externen Web-Host der iq digital (AWS-CDN)
- Hosting und Abruf des AC-Deployment vom iq-CDN
- Abruf des AC-Script-Deployments vom Web-Server des Seitenbetreibers (empfohlen)
- Alternativ zum Hosting und unmittelbaren Abruf des AC-Deployment vom iq-CDN wird eine direkte Implementierung des Adcontrollers über den Webserver des Seitenbetreibers empfohlen. Voraussetzung ist eine weiterhin flexible Anbindung des AC- Deployment als PRELIVE- und SANDBOX-Version (siehe "Auslieferungsmodus") durch den iq-Entwickler mittels iqdeployment-Parameter. Es gibt hierzu bereits unterschiedliche Umsetzungen im Einsatz, die wir gerne gemeinsam mit Ihnen abstimmen.
Caching AdController
Für ein optimiertes Ergebnis hinsichtlich Performance und aktuelle Version des AC-Deployment stimmen wir Möglichkeiten zum kurzfristigen Cachen sowie Expire-Varianten gerne gemeinsam mit Ihnen ab. Die sichere Ausspielung ist dabei voranzustellen, so dass durch iq digital erforderliche Änderungen im AC-Deployment auch sofort beim User in die Ausführung kommen und nicht durch ältere Versionen im Cache blockiert werden.
Auslieferungsmodus
Die Variable iqd_mode (siehe Code Beispiel zur Umsetzung von AdController) referenziert, die geplante LIVE Version des AdControllers, oder eine von LIVE abweichende Version (z.B. PRELIVE- oder SANDBOX- Version des AC-Deployments). Durch die URL-Parametererweiterung "iqdeployment=[platzhalter]" ist es dem iq-Entwickler möglich eine Vorabversion des AC-Deployments, ohne Umstellung der Website oder Implikation der Webseitenbesucher, während des Live- Betriebs zu testen bzw. bereitzustellen.
Code-Beispiel zur Umsetzung im <head>-Tag des Dokuments (die Trennung der Script-Blöcke ist erforderlich).
Der Wert für das Makro [cdn_partnersite_Folgt_durch_iq] wird von iq zur Verfügung gestellt.
Einbindung auf einer nicht-reponsive Seite
<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';
})();
//VARIANTE 1:
IQSLoader("https://s3.eu-central-1.amazonaws.com/prod.iqdcontroller.iqdigital/[cdn_partnersite_Folgt_durch_iq]/" + iqd_mode + "/iqadcontroller.js.gz ");
//VARIANTE 2:
IQSLoader("https://[publisher_directory]/[cdn_partnersite_Folgt_durch_iq]/" + iqd_mode + "/iqadcontroller.js.gz");
</script>
Einbindung auf einer responsive Seite (Beispiel Implementierung)
<script>
function isDesktop() {
var width = (window.innerWidth > 0) ? window.innerWidth : screen.width;
return width >= 850;
}
function isMobileOrTablet() {
return !isDesktop();
}
function isTablet() {
return isMobileOrTablet() && window.outerWidth >= 480 && window.hasOwnProperty('orientation');
}
function isMobile() {
return isMobileOrTablet() && !isTablet();
}
function getPlatform() {
if (isDesktop()) {
return 'desktop';
}
if (isTablet()) {
return 'tablet';
}
return 'mobile';
}
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';
})();
if (isDesktop()) {
IQSLoader(
"https://s3.eu-central-1.amazonaws.com/prod.iqdcontroller.iqdigital/[cdn_partnersite_Folgt_durch_iq]/" +
iqd_mode + "/iqadcontroller.js.gz");
} else {
IQSLoader(
"https://s3.eu-central-1.amazonaws.com/prod.iqdcontroller.iqdigital/[cdn_partnersite_Folgt_durch_iq]/" +
iqd_mode + "/iqadcontroller.js.gz");
}
</script>
AdController proxy
<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>
Mandanten-CMS-Objekt (Seiteninformationen für AdController-Konfiguration)
Allgemeine Informationen
Um unter Anderem die anzuwendende Konfiguration für die aktuelle Angebotsseite festzustellen, werden dem AdController über dieses Objekt notwendige Informationen des Seitenbetreibers übergeben. Das vom Seitenbetreiber bereitzustellende Mandanten-CMS-Objekt übermittelt die seitenspezifischen Informationen zur Auswahl der gültigen bzw. spezifischen AdController-Konfiguration und inventargerechten Anzeigenanforderung.
Code-Beispiel zur Umsetzung im <head>-Tag des Dokuments nach der AdController Einbindung:
<script>
// ########### CMS-MANDANTEN-OBJECT #############
var cmsObject = {};
cmsObject = {
$handle: "[Erfolgt_mit_Abstimmung_iq]",
level2: "[Erfolgt_mit_Abstimmung_iq]",
level3: "",
level4: "",
isWrapperApp: [true,false],
keywords: "[Erfolgt_mit_Abstimmung_iq]",
tma: "[Erfolgt_mit_Abstimmung_iq]",
platform: "[desktop | tablet | mobile]"
};
</script>
Schlüssel Informationen
Schlüssel: $handle
Die Zuordnung von einer Seite der Webpräsenz zu einer Subsite des iq digital Tag Management Systems (TMS), deren Konfiguration für die aktuelle Seite wirksam ist, erfolgt über das $handle-Matching-Kriterium. Die Anzeigen-Vertaggung erfolgt somit nach vermarktungsrelevanten und technisch abbildbaren CMS-Layout-Typen der Webpräsenz. iq digital liefert soweit möglich die für das Matching relevanten und zuvor abgestimmten $handle-Bezeichner für die definierten Layout-Cluster - z.B. Homepage ($handle:'homepage'), Übersichts- und Sub-Übersichtsseiten ($handle:'index'), Detailseiten ($handle:'index'), Artikelseiten ($handle:'artikel'). Je nach redaktioneller Layout-Struktur und Anforderungen zur Ansteuerungen der Webpräsenz kann eine granulare oder flache $handle-Clusterung erforderlich sein. Für die optimale Zuordnung ist durch den Seitenbetreiber eine Site-Map mit abgesprochenen und "offenen" Layout-$handle-Zuordnung zur Verfügung zu stellen.
Schlüssel: level2, level3 und level4
Enthalten seitenspezifische Informationen für die erforderliche Inventarisierung der Publisher-Site im Ad Server und den AdRequest- URL-Builder zur Anforderungen der auf dieses Inventar gebuchten Anzeigen. Die Level-Informationen sind in Abhängigkeit der Ressort- bzw. Umfeld-Tiefen zu füllen insofern vermarktungsrelevant. Beispiel: Wenn die Seite eine Rubrik 'Politik' hat und diese eine Unterrubrik 'Außenpoltik', dann wäre den Wert für level2:'politik' und für level3:'aussenpolitik'
Schlüssel: isWrapperApp
Anhand von diesem Wert sollte die Information an uns übermittelt werden, ob es sich bei der Ausspielung um eine Wrapper App handelt oder nicht. Möglich Werte hierzu sind true oder false.
Schlüssel: keywords
Hier kommen die Werte aus level2, level3, level4 mitrein. Zusätzlich können hier weitere Schlagwörter optional hinzugefügt werden, die die Seite beschreiben und für besseres Kampagnien-Targeting helfen können.
Schlüssel: tma
Dieses Wert ist optional, sollte jedoch befüllt werden, wenn es sich hierbei um eine Themenseite oder Themenunterseite handelt. Der Wert ist hier der Name von dem Thema, um das es sich hier handelt.
Schlüssel: platform
Hier sind folgende Werte möglich: desktop, tablet oder mobile Je nachdem auf welchen Device der User unterwegs ist sollte der entsprechende Wert übergeben werden.
Zeichenlimitierung
Alle Informationen im CMS-Objekt sind ausschließlich klein zu schreiben; Leerzeichen, Sonderzeichen und Umlaute sind nicht erlaubt. Die einzige Ausnahme ist das "_" Zeichen (Unterstrich/Underscore).
FALSCH: Archäologie RICHTIG: archaeologie | FALSCH: Psychologie-Hirnforschung RICHTIG: psychologie_hirnforschung
AdController initialisieren
Nach dem Setzen von dem cmsObject muss der AdController initialisiert werden wie folgt:
<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>
Mandanten-SiteMap (Übersicht AdController-$handle-Zuordnung)
Zum besseren Verständnis Ihrer Website-Struktur und deren Verwaltung in Ihrem CMS ist die Bereitstellung einer Site-Map des Angebotes wünschenswert. Des Weiteren ist die Klärung folgender Fragen für die AC- Implementierung wichtig.
- Generierung eines generellen Verständnisses des Mandanten-Content-Managements
- Welche Angebote werden über das eigene Redaktionssystem betrieben?
- Welche Angebote werden von externen Dienstleistern (Content-Partnern) betrieben. Gibt es abweichende Voraussetzungen für die AC-Implementierung, z.B. Cross-Domain-Integrationen via IFrame?
- Welche Cluster, Limitierung für die Angebotsansteuerung- bzw. -aussteuerung ist durch das CMS-Layout-Templating vorgegeben?
- Welche Angebote sind derzeit nicht vermarktet und werden auch zukünftig keinen AdController einbinden?
- Welche Angebote sind derzeit vermarktet ggf. aber nicht sofort bzw. zum vereinbarten Timing mit dem AdController implementiert?
- Problem: Ggf. Unterschiedliche AdServer-Technologien parallel im Einsatz
- Timing erforderlich, wann diese Angebote nachgezogen werden können
- Zuordnung des CMS-Layout-Templating zu AdController-$handle-Cluster
- Die Möglichkeit eine individuelle Tagging-Konfiguration für einen bestimmten Angebotsbereich wirksam zu machen ist nur gegeben, wenn auch ein eigenes AdController-$handle für die Konfigurationsauswahl im AC-Deployment vergeben wurde
- I.d.R. erfolgt das $handle-Cluster Layout-basiert (z.B. Homepage, Startseiten, Detailseiten, …) da die Vermarktung entsprechende Produktpakete zur Umfeld-Vermarktung erfordert und Anzeigenpositionen oftmals in Layoutabhängigkeit stehen
- Zielsetzung ist, nicht für jedes abweichende Layout im Angebot auch ein eigenes $handle-Cluster bzw. eigene Konfiguration bereitzustellen, sondern nicht relevante bzw. produktunabhängige Reichweitenangebote in passende Cluster zusammenzufassen. Es gilt der Grundsatz - so viel $handle-Bezeichner wie nötig, so wenig wie möglich. iq kann zu diesem Zweck mehrere von der Redaktion bereitgestellt Cluster verdichten, so dass zwar eine granulare Kennzeichnung erfolgt, jedoch immer dieselbe Konfiguration im AdController zur Ausführung kommt. Ein Vorteil ist, dass iq digital in diesen Fällen bei späterem Bedarf spezifische Konfigurationen nach Auflösung solcher Bundle vergeben kann
Bitte stellen Sie die Zuordnung der Layout-$handle nur in Absprache mit iq digital zur Verfügung. Je nach Anforderung kann es zu unterschiedlichen Ergebnissen kommen.
Anzeigen-Containermodell
Die Anzeigen-Container werden nach einem im Voraus abgestimmten Vertaggungsplan in der Publisher Seite nach einem vorgegebenen Muster integriert.
<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>
Zur richtigen Identifizierung aller Platzhalter müssen folgende Informationen allen Platzhalter Div-Containern mitgegeben werden:
- Die Klasse "iqdcontainer". Durch diese Klasse werden alle Divs Werbeplatzhalter gekennzeichnet.
- Das Data Attribute "data-placement". Über dieses Data-Attribut können die jeweiligen Positionen in der Seite eindeutig erfasst werden.
- Das Data Attribute "data_device". Über dieses Data-Attribut wird gekennzeichnet, ob der Werbeplatz für die Desktop, Mobile oder Tablet Werbeausspielung gedacht ist. Mögliche Werte: desktop | tablet | mobile
SonderPositionen
Alle Positionen im Footer und Header bekommen keine Zahl in "data-placement", sondern jeweils "pos_header" oder "pos_footer", wodurch sie eindeutig bestimmt sind.
<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>
Anzeigenplatzierungen Signalfunktionen
AdController.finalize(..)
Die Web-Seite signalisiert dem AdController mit dem AdController.finalize-Aufruf, dass die Render-Phase abgeschlossen werden kann, da keine weiteren Anzeigen-Anforderungen von der Seite implementiert sind. In Einzelfällen kann es dazu kommen, dass die geplante AdController-Konfiguration für die aktuelle Seite von den tatsächlich implementierten Anzeigeplatzierungen abweicht. In diesem Fall werden die Abweichungen durch den AdController evaluiert, abgefangen und bei Bedarf protokolliert. Abweichungen können immer dann Auftreten, wenn für das betroffene Angebot keine spezifische $handle-Zuordnung geplant wurde. Das kann auch ein durch iq digital gewünschtes Szenario sein.
<script>
AdController.finalize(); //Signalisiert dem AdController, dass keine weiteren AdCall-Aufrufe auf dieser Seite folgen
</script>
IQDComplete() - Page-Load Signal
Sobald alle Inhalte auf der Seite (auch verzögert dynamisch geladener Content), die zur Höhenberechnung der Seite beitragen, geladen worden sind, soll ein Signal an iq digital gesendet werden:
<script type="text/javascript">
var IQDComplete = {
init: function () {
return true;
}
};
</script>
Bereitstellung Entwicklungsumgebung
Für die ordnungsgemäße Umsetzung und Gewährleistung des AdControllers hinsichtlich Betriebsbereitschaft der Webpräsenzen und Sicherstellung der gegenwärtigen und zukünftigen Vermarktungskonzepte durch iq digital ist die Umsetzung auf einer vollumfänglichen Entwicklungsumgebung für die initiale Vertaggung der Seiten durch den AdController erforderlich.
Ziel ist die Sicherstellung einer realen, dem LIVE-Betrieb entsprechenden Umsetzung des AdControllers auf einem parallelen System, welches LIVE gestellt wird, wenn das finale SetUp und Testing von beiden Seiten abgeschlossen wurde.
Die Bereitstellung des AdControllers für die Web-Seiten wird über verschiedene Kanäle erfolgen. Änderungen und weitere Entwicklungen im Rahmen von Konfigurationsanpassungen oder Technologieerweiterung für eine Seite erfolgen bei iq digital über ein Preview-Deployment. Die derzeitige Einbindung des AdControllers sieht bereits einen dynamischen Switch zwischen LIVE- und PRELIVE- Version des AdControllers vor, die auf Clientseite mit einer GET-Parameter-Erweiterung in der URL gesteuert werden kann "https://www.domain.de?iqdeployment=prelive".
Die CMP, die auf die Liveseite verwendet wird, sollte außerdem auch auf die Testseite implementiert sein.
Fluide/Responsive Webanwendungen
Wenn Sie eine fluide bzw. responsive Webanwendung betreiben um unterschiedliche Kanäle im Rahmen des stationären Desktop- und Mobilen-Webs mit schlankeren Code und einheitlichen Redaktionssystem zu pflegen, ist eine Abstimmung der für die Vermarktung relevanten Punkte im Vorfeld erforderlich. Für den Fall des AdControllers bedeutet das, dass Anzeigenplatzierungs-Konzepte für Desktop-Web und Mobile aufeinander plausibel abgestimmt werden müssen. Bitte stellen Sie iq digital eine Übersicht Ihrer Layout- Lösung mit darin geplanten Sprungmarken, ggf. adaptiven Layout-Anpassungen und Device-Detektionen zur Verfügung.
Beim Wechsel vom Layout für Desktop-Web zur Mobile-optimierten Ansicht ist die Implementierung eines gesonderten AC-Mobile- Deployments erforderlich, sobald Ihr Code zur Device-Detektion das entsprechende Umfeld identifiziert. Des Weiteren lassen sich dann die Anzeigenplatzierungen des Desktop-Webs nicht 1:1 auf das zu diesem Zeitpunkt Mobile-optimierte Design übertragen, da Anzahl und Position der Platzierungen bei fluider Neu-Anordnung des HTML-MarkUps nicht den verschiedenen Vermarktungsanforderungen dieser Umfelder entsprechen. Bitte stimmen Sie sich gemeinsam mit iq digital bzgl. eines entsprechenden Platzierungs-Konzeptes ab.
Entsprechende Anforderungen und Konzepte sind bereits im Vermarktungsportfolio von iq digital im Einsatz, gerne Leisten wir Hilfestellung im Rahmen bereits aktiver Implementierungen.
Single Page Applikation (Kein Pageload)
Der Mandant muss im Falle einer SPA Implementierung beim Seitennavigieren dafür sorgen, dass:
- cmsObject muss neu gesetzt werden
- AdController muss reinitialisiert wird
- Render Funktionen müssen erneut aufgerufen werden
- eine postMessage() Nachricht an uns geschickt wird ( siehe Abschnitt Callback-Funktion zum Nachladen der Anzeigenpositionen)
Callback-Funktion zum Nachladen der Anzeigenpositionen
Folgende postMessage muss an iq gesendet werden, sobald dies mit iq schon abgestimmt wurde, um ein Nachladen der Anzeigen anzustoßen:
<script type="text/javascript">
window.top.postMessage("iq_refresh_ads","[targetOrigin]");
</script>