Einbau des Google Mobile Ads SDK

Aus Dokumentation
Zur Navigation springen Zur Suche springen

Offizielle Dokumentation zum Google Mobile Ads SDK

Das Google Mobile Ads SDK (GMA SDK) bringt alles mit, was für eine Werbeausspielung in nativen Apps benötigt wird.

Getting Started zum Google Mobile Ads SDK

GMA SDK iOS Getting Started GMA SDK iOS Getting Started

Download des Google Mobile Ads SDK

Android

Das GMA SDK ist in den Android Play Services integriert und deshalb auf den Android Geräten vorhanden.

iOS

Für iOS kann das GMA SDK hier heruntergeladen werden: Download iOS

Ad-Manager vs. Admob

Die Dokumentation zum Google Mobile Ads SDK gibt es in zwei Varianten: für Ad-Manager- und Admob-Nutzer. Die iq digital ist ein Ad-Manager Kunde, deswegen muss unbedingt darauf geachtet werden, dass in der Browser-URL https://developers.google.com/ad-manager/... enthalten ist. Die Admob Doku unterscheidet sich leicht von der Ad-Manager Doku.


Kurze Einführung in den Lebens-Zyklus einer Werbeausspielung mit dem GMA SDK

Am Beispiel einer Banner-Werbeausspielung wird hier kurz der Lebens-Zyklus einer Werbeausspielung erklärt.

Request

Das Adrequest wird in der App zusammengestellt und besteht aus mehreren Komponenten. Für eine erfolgreiche Werbeausspielung sind folgende Komponenten wichtig:

Consent String
Die App benötigt vom Nutzer einen gültigen Consent für die Werbeausspielung. Dabei sind neben mehreren relevanten Purposes auch der Vendor 755 Google Advertising Products notwendig (s.u.)
Creative-Sizes
In den meisten Fällen benutzen wir multisize-Adrequests. Das bedeutet, dass das Adrequest mehrere Creative Größen enthälkt und der Adserver daraufhin prüft, ob er ein Creative für eine dieser Größen zur Verfügung hat. Beispiele sind z.B. 320x1, 320x53, 320x80, 320x106, 320x160 etc.
Adunit
Die Adunit ist die Adresse der Werbeplatzierung. Damit weiß der Adserver, auf welcher Seite eine Werbeausspielung erfolgt. Die Adunit ist gleich für alle Adrequests eines Pagerequests. Beispiel: /183/Rheinischer_Kurier_ios_phone/homepage
Keywords (optional)
Keywords sind Key-Value Paare und können eine Werbeplatzierung um weitere Informationen anreichern, die für eine gezielte Werbeausspielung notwendig sind. Die Werbeplatzierungen der iq digital enthalten alle eine bestimmte Bezeichnung, welche über die Keywords dem Adserver mitgegeben wird. Beispiel: kw=iqadtile1,digtransfrom&tile=1&doc=homepage

Adserver

Wenn der Adserver gültigen Consent besitzt, prüft ein Verteilungsalgorithmus, ob eine oder mehrere Werbebuchungen für die Adunit, Creative sizes und Keywords vorliegen. Ist dies der Fall wählt der Adserver die beste dafür aus. Sind mehrere Buchungen gleich wichtig, wählt er zufällig eine davon aus. Nur im Falle keiner Buchung würde er eine no ad oder no fill Meldung ausgeben, die besagt, dass für die Kombination aus adunit, creative size und Keywords keine Buchung existiert.

Ausspielung innerhalb der App

Die App lädt die Response des Adservers, die aus dem Template-Code und den Creative Komponenten besteht. Dabei ist zu beachten, dass der Werbecontainer auf die creative size des ausgelieferten Creatives vergrößert wird. Für Fullscreen Ads muss diese Größe von der App nachträglich auf die Display Viewport Größe (also device independent pixel) angepasst werden. Im Falle einer Banner Anzeige bekommt die App meist nach dem Ladevorgang ein oder mehrere setsize-Events über den einzubauenden AppEventHandler und muss den Werbecontainer auf die neue Größe anpassen, sofern diese sich von der creative size unterscheidet.

Impression-Zählung

Eine Impression Zählung, die misst, dass ein Ad angesehen wurde, wird vom GMA SDK automatisch abgeschickt, sobald mindestens 1px im sichtbaren Bereich des Displays ist.


Allgemeine Informationen

Adunits (Zonierung)

Der Google Ad Manager benutzt zur Adressierung der Seiten Adunits, die sich wie folgt zusammensetzen können:

  • /netzwerkId/level1
  • /netzwerkId/level1/seitentyp
  • /netzwerkId/level1/level2/seitentyp
  • /netzwerkId/level1/level2/level3/seitentyp
  • usw.

Begriffserklärung

netzwerkId
Hier ist immer die Netzwerk ID der iq digital einzugeben: 183
level1
Dies ist die Bezeichnung der App im Google Ad Manager und wird von der iq digital vorgegeben. Die Bezwichnung besteht aus <appname>_app_<plattform>_<gerätetyp>.
appname
Der Name der App
plattform
Das Betriebsystem, also ios oder android
gerätetyp
Der Gerätetyp, also phone oder tablet
level2
Dies ist die Bezeichnung einer Rubrik der App, z.B. politik
level3 (usw.)
Dies ist die Bezeichnung für eine Unterrubrik, z.B. im Falle von politik als level2 wäre ausland eine Unterrubrik für level3. Level4 und höher sind weitere tiefere Verzweigungen der App, diese werden im Normalfall nicht also Adunits angelegt und solche Seiten würden unter dem level3 angelegt werden.
seitentyp
In Apps mit Banner-Anzeigen (z.B. News Apps) bezeichnet seitentyp die unterschiedlichen Seitentypen, also ob es sich z.B. um eine Übersichts-, Artikel- oder Bildergalerieseite handelt. Übliche Werte dafür sind homepage, index, artikel, bildgal. In Apps mit Fullscreen-Anzeigen (z.B. epaper oder Zeitungs Apps) werden mit seitentyp die unterschiedlichen Anzeigeplätze innerhalb der Rubrik gemeint, also ob es sich z.B. erste, zweite oder dritte Swipe Anzeige handelt. Übliche Werte sind openingpage, swipe_1, swipe_2, swipe_3 usw.

Beispiel für die fiktive Rheinischer Kurier News App mit Banner-Anzeigen:

  • /183/Rheinischer_Kurier_app_ios_phone
  • /183/Rheinischer_Kurier_app_ios_phone /homepage
  • /183/Rheinischer_Kurier_app_ios_phone/politik/index
  • /183/Rheinischer_Kurier_app_ios_phone/politik/artikel
  • /183/Rheinischer_Kurier_app_ios_phone/politik/bildgal
  • /183/Rheinischer_Kurier_app_ios_phone/sport/index
  • /183/Rheinischer_Kurier_app_ios_phone/sport/artikel
  • /183/Rheinischer_Kurier_app_ios_phone/sport/bildgal

Beispiel für die fiktive Rheinischer Kurier Epaper iPad App mit Fullscreen-Anzeigen:

  • /183/Rheinischer_Kurier_app_ios_tablet
  • /183/Rheinischer_Kurier_app_ios_tablet/preloading_ad
  • /183/Rheinischer_Kurier_app_ios_tablet/openingpage
  • /183/Rheinischer_Kurier_app_ios_tablet/politik/swipe_1
  • /183/Rheinischer_Kurier_app_ios_tablet/politik/swipe_2
  • /183/Rheinischer_Kurier_app_ios_tablet/politik/swipe_3

Wichtig:

Der Adserver DFP erlaubt keine Sonderzeichen in den Adunits mit Ausnahme des Unterstrichs "_". Auch Umlaute und ß sind nicht erlaubt. level2, level3 und seitentyp sollten auch komplett kleingeschrieben werden. Generell sind die Adunits vom Google Ad Manager so gedacht, dass sie sich dynamisch aus dem CMS des Mandanten generieren lassen. Sollte das CMS so angelegt sein, dass eine andere Benennung sinnvoll erscheint, muss die iq digital frühzeitig kontaktiert werden, damit eine sinnvolle Lösung für alle Beteiligten gefunden werden kann. Bei Rubriken mit einem "und" bzw. einem "&" im Namen, wie z.B. Wirtschaft & Politik, bietet es sich an, nur die Hauptwörter getrennt mit einem Unterstrich aufzuführen, also wirtschaft_politik.

Creative Sizes

Im Google Ad Manager stehen die creative sizes für die Werbemittel-Größen. Dabei ist es möglich dass die tatsächlich ausgespielte Größe eines Werbemittels von der creative size abweicht. Die App muss für ein Adrequest der entsprechenden Platzierung alle zugehörigen Creative Sizes abfragen. Die lange Liste bei der Platzierung "Oben" ergibt sich aus den creative sizes für Direkt- und Programmatische Vermarktung. Diese Platzierung ist ein Beispiel für Banner-Platzierungen und dort wird nie nach Portrait und Landscape in den creative sizes unterschieden. Bei der Platzierung "Richmedia" ergibt sich die Liste für 7Zoll Tablets und 10 Zoll Tablets und dort jeweils für Portrait und Landscape. Diese Platzierung ist ein Beispiel für ein Fullscreen Ad und hier wird in den creative sizes zwischen Portrait und Landscape Modus unterschieden. Unterstützt eine App nur Portrait-Modus, reicht es aus, dass sie nur die Portrait creative-sizes benutzt. Tablets mit einer Auflösung kleiner als 750x1024 müssen die 7Zoll Tablet creative-sizes benutzen, da das Google SDK es nicht erlaubt Anzeigen mit einer creative-size größer als die Geräte Auflösung abzurufen. Zur Info: In beiden Beispielen gilt, dass wir die Größen nur als Pseudogrößen benutzen und skalieren die deutlich größeren Anzeigen für eine optimale Darstellung. Eine vollständige Übersetzungstabelle der Smart FormatIds zu GPT creative sizes befindet sich in der Tabelle Adslot_Ids_Uebersetzung_Smart_nach_GPT.xslx

Beispiele für Creative Sizes einer Banner Platzierung:

320x1, 320x50, 320x53, 320x80, 320x160, 320x320, 300x50, 300x75, 300x100, 300x150, 300x250

Beispiele für Creative Sizes einer Fullscreen Platzierung auf einem Android Tablet:

310x480, 480x310, 750x1024, 1024x750

Links zu Creative Sizes im Google Mobile Ads SDK:

und

Keywords (Anhängen von Key-Value-Paaren)

Ein Adrequest bekommt als CustomTargeting immer eine Gruppe aus Key-Value Paaren. Dabei können mehrere Werte (Values) mit einem Komma separiert sein. Diese Keywords haben mehrere Funktionen:

  • bestimmte Buchungen liefern nur aus, wenn diese Keywords existieren (z.B. bei bestimmten Produkten oder auch bei Testschaltungen)
  • Buchungen können über solche Keywords von der Auslieferung ausgeschlossen werden (z.B. um fehlerhafte Darstellungen einer Werbebuchung zu verhindern)
  • solche Keywords erlauben detaillierte Auslieferungs-Berichte (Reports)

Die iq digital benutzt dabei bestimmte Key-Value-Paare. Hier sind die wichtigsten Keys erklärt:

kw
Generelle Keyword Liste. Hier sind meist mehrere Werte mit Komma separiert. Üblich sind einige Legacy-Werte (z.B. digtransform,nospa,enozqi). Hinzu kommen Bezeichner für die App oder die Seite (z.B. Rheinischer_Kurier_app_ios_phone), sowie die Werbeplatzierungsbezeichnung (z.B. iqadtile3).
tile
Die Nummer der Werbeplatzierung. Im Falle eines iqadtile3 also als Wert 3.
doc
Die Bezeichnung des Seitentyps. Gültige Werte sind homepage, index, artikel, bildgal
iqadtype
Die Angabe der Plattform. Gültige Werte sind online, mew, app, amp
appver
Die Bezeichnung der Appversions-Nummer (s.u.)

Angaben welche Keywords für welche Platzierung verwendet werden sollen, finden sich in der creative_sizes_and_keywords.xlsc Tabelle, die von der iq digital zu Projektstart zur Verfügung gestellt wird.

Links zum CustomTargeting im Google Mobile Ads SDK

Debugging

Es muss eine "Easter-Egg"-Funktion eingebaut in die App eingebaut werden, damit die iq digital Probleme und neue Werbeformen mit der Live App testen kann. Beim Smart SDK konnte dies durch ein IP-Targeting gewährleistet werden. Der Adserver DFP bietet leider keine solche Möglichkeit, weswegen die App ein manuell zu setzendes Testkeyword beim Adrequest einbauen muss. In einem selten frequentierten Bereich der App, wie dem Impressum sollte es daher die Möglichkeit für Eingeweihte geben, einen kleinen Dialog aufzurufen. Durch diesen kann man ein selbst gewähltes Keyword jedem zukünftigen Adrequest anhängen. Gleichzeitig oder durch das Setzen eines Häkchens würde der Debug-Modus, um die Werbe Webviews in der Android App auf dem Desktop Chrome zu inspizieren, aktiviert werden. if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) { 

   WebView.setWebContentsDebuggingEnabled(true);

}

Danach kann man unter Android die Webviews der App im Desktop Chrome mit inspect einsehen. Dies ermöglicht uns Fehler in der Werbedarstellung besser zu analysieren. Ohne ein Debug Easter Egg in der App könnten wir nach Livegang keine Testschaltungen aufsetzen und auch keine Probleme analysieren. Dies würde die Wartung der App von unserer Seite verhindern und auch dem Mandanten keine Möglichkeit geben, selber seine App mit Testwerbung zu überprüfen. Die Keyword-Funktion ist daher notwendig, um den Personenkreis einzuschränken, der die Testschaltungen zu Gesicht bekäme. Das Anhängen der Keywords ist beim Punkt "Anhängen von Key-Value-Paaren" genauer erklärt. Mehrfache Keywords müssen mit durch Kommata separiert werden. Es gibt vielfältige Optionen, wie das Easter-Egg aktiviert werden kann. Mehrfache/unsinnige Taps auf UI-Elemente oder eine ganz spezielle Eingabe ins Suchfeld seien hier beispielhaft genannt. Wir erlauben uns aber die Vorgabe, dass sich unter Android und iOS zur Aktivierung identisch verhält. Bei der Art der Aktivierung des Debug-Easter-Egg stehen wir gerne beratend zur Seite.

App-Versions-Targeting

Es soll die Möglichkeit geben, dass wir ältere App-Versionen, die noch im Spiel sind, aber einen in Hinblick auf die Werbung relevanten Bug aufweisen, von der Werbeausspielung ausschließen können. Die addCustomTargeting Methode (siehe oben Punkt "Anhängen von Key-Value-Paaren"), müsste dazu benutzt werden. Nur würde hier nicht als Key "kw" sondern "appver" benutzt werden. Damit das Ganze auch praktikabel ist, bedarf es hier ein bisschen Fingerspitzengefühl, was das Value angeht. Das Problem ist, dass wir diese Werte lediglich als Zeichenketten im AdServer sehen und daraufhin operieren können. Wir können zwei Strings lediglich abgleichen. Was leider nicht geht, ist eine Bedingung wie "Wenn die Appversion kleiner oder gleich 3, dann dort keine Werbe-Ausspielung". Es darf also nicht inflationär viele verschiedene Versionsnummern gleichzeitig in der Gesamtheit der Nutzer geben. Sinnvoll wäre also eine Major-Versionsnummer und ein oder zwei "Nachkommastellen", getrennt mit einem Unterstrich. Also z.B. "1_12". Gewünscht ist nicht eine extra Versionsnummer nur für die Werbung, sondern ein sinnvoller Substring der internen Versionierung. Entscheidend ist aber, dass dieser Wert zumindest dann inkrementiert wird, wenn sich irgendwie Auswirkungen auf die Werbeintegration ergeben könnten. Mit Fingerspitzengefühl meine ich konkret, dass man sich die Frage stellt... • Wird das Google Ads SDK in einer neuen Version benutzt? -> immer inkrementieren • Wurde etwas an den Aufrufen der Methoden des Google Ads SDK verändert, z.B. Timings? -> immer inkrementieren • Wurde etwas an der Swipe-View-Struktur verändert? -> besser inkrementieren • Wurde etwas am Layout verändert? -> vielleicht inkrementieren Bei den beiden erst genannten Punkten gehen wir davon aus, dass das nicht ohne Rücksprache mit uns erfolgt.

Wichtige Hinweise zu dieser Anleitung

Die Zonen (Adunits) für die Werbeplatzierungen werden von uns erst zu Projektstart erstellt und mit Testwerbung belegt. Anschließend werden die Adunits an den Mandanten übermittelt. Bitte nicht mit der im SDK fest eingebauten Logik für Test-Werbemittel arbeiten: request.testDevices = @[ kGADSimulatorID ]; (iOS) oder addTestDevice(String); (Android) Stattdessen sind auf den Zonen Buchungen mit Test-Werbemitteln aktiv. Die werden zum Launch einfach gestoppt. Die Zonen selbst ändern sich zum Live-Betrieb nicht.



Ansprechpartner iq digital

Die iq digital steht für Fragen und Kommentare gerne zur Verfügung. Sollten wir einmal nicht weiterhelfen können, ist es uns möglich einen Entwickler von Google als Ansprechpartner in die Diskussion mit einzubeziehen. Tim Lohmann (Mobile Developer) Telefon +49 211 887 2336 E-Mail tim.lohmann@iqdigital.de


Wichtige Dokumente

Übersetzungshilfe von Smart nach GPT: • Adslot_Ids_Uebersetzung_Smart_nach_GPT.xlsx Liste der Zonen: (diese dienen nur als Orientierungshilfe. Die Apps sollten diese Zonen dynamisch aus dem CMS generieren) <appname> muss durch den entsprechenden App Namen ersetzt werden. • zonen_<appname>_android_tablet.txt • zonen_<appname>_ios_tablet.txt • zonen_<appname>_ android_phone.txt • zonen_<appname>_ios_phone.txt

AppEvent-Handler Vorlage für Android • PublisherAdAppEventListener.java

 

Preloading Ad / Interstitial

Beschreibung

Das Preloading Ad ist eine Interstitial-Werbeform die während/nach dem Splashscreen angezeigt wird, aber auf jeden Fall bevor der Content angezeigt wird. Die Werbeform wird für 5sek angezeigt und schließt sich automatisch bzw. wenn der Benutzer den Close-Button betätigt. Die App sollte das Ad nicht selber schließen. Sollte die App nach dem Absenden des Adrequests unverhältnismäßig lange auf die Antwort des Adservers warten, muss die App das Request abbrechen und automatisch den Content laden. Wir empfehlen hierfür 5-10s Wartezeit. Sollte innerhalb dieser Zeit die Antwort vom Adserver zurückkommen, sollte die App die Werbung nicht mehr abbrechen, sondern dies der Werbeschaltung überlassen (wegen des auto-close). Der Nutzer kann über den Close-Button (wird durch das iq digital Template erzeugt) jederzeit vorzeitig abbrechen. Das Interstitial ist eine Overlay-Werbeform, die sich vollflächig über den Content legt. Die Werbeform wird für 5sek angezeigt und schließt sich automatisch bzw. wenn der Benutzer den Close-Button betätigt. Die App sollte das Ad nicht selber schließen. Der Nutzer kann über den Close-Button (wird durch das iq digital Template erzeugt) jederzeit vorzeitig abbrechen. Werbemittel für die Anzeige können in Tablet Apps bis zu 768x1024px groß, in Smartphone Apps bis zu 640x920px groß sein (oder auch kleiner). Sollte das Display größer sein, wird das Werbemittel zentriert, bei kleineren Displays wird entsprechend kleiner skaliert. Dies geschieht durch iq digital. Bei einem Interstitial wird automatisch die Anzeige auf Fullscreen Größe angepasst. Das Werbetemplate reagiert automatisch und skaliert die Werbung entsprechend. Bei einem Interstitial Adrequest (technisch ist für DFP ein Preloading Ad ein Interstitial) wird keine creative-size angegeben. Das SDK verwendet automatisch die creative-sizes 320x480 bzw. 480x320 oder 768x1024 bzw. 1024x768. Ein bisher vorhandener Aufruf des SMART-SDK muss hier ersetzt werden durch den Aufruf des Google Ads SDK. Es gelten die gleichen Abbruchkriterien. 2.2 Wichtige Klassen für das Preloading Ad und Interstitial (iOS und Android): https://developers.google.com/android/reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest.html https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/api/reference/Classes/DFPRequest https://developers.google.com/android/reference/com/google/android/gms/ads/doubleclick/PublisherInterstitialAd https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/api/reference/Classes/DFPInterstitial Auf iOS wird so der Erfolg des Ladevorgangs ermittelt: https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/banner#adviewdidreceivead

Auf Android verhält es sich entsprechend mit diesen Methoden public void onAdLoaded () public void onAdFailedToLoad (int errorCode) https://developers.google.com/android/reference/com/google/android/gms/ads/AdListener

Anhängen von Key-Value-Paaren:

Bei dem PreloadingAd Request bitte das Keyword iqadtilePre mitgeben. ( Also addCustomTargeting("kw","iqadtilePre") ). Bei einem Interstitial Request bitte das Keyword iqadtileOOP mitgeben. ( Also addCustomTargeting("kw","iqadtileOOP") ). Zusätzlich wird bei PreloadingAd und Interstitial das Key-Value-Paar tile=0 benötigt (addCustomTargeting("tile","0")).  

Fullscreen Anzeigen (auch Swipe Anzeigen genannt)

Kurzbeschreibung der Werbeform

Die Werbeplatzierungen sind Display ausfüllende Anzeigen, die zwischen zwei regulären Seiten in der App angezeigt werden. Grundsätzlich ist die Werbeseite nachfolgend zu ihrer zugeordneten Content-Seite, z.B. Politik/swipe_1 meint, dass zuerst die 1. Politik-Content-Seite angezeigt wird und beim nächsten Swipe die Werbe-Seite erscheint. Sollte keine Werbung gebucht sein, darf die Werbeseite nicht angezeigt werden. Andernfalls ist mit Weißräumen zu rechnen. Es ist also eine dynamisch generierte Pseudo-Seite.

Position innerhalb der App

Die Platzierung ist dynamisch zwischen zwei Content-Seiten eingebettet. Dabei befindet sich die Werbeplatzierung immer rechts neben der Seite, die Ihr im Content zugeordnet ist, z.B. Politik/swipe_1 meint, dass zuerst die 1. Politik-Content-Seite angezeigt wird und beim nächsten Swipe die Werbe-Seite erscheint

Der Adrequest für diese Platzierung soll dann abgeschickt werden wenn der Ladevorgang sicher abgeschlossen werden kann, bevor der User die Pseudo-Seite erreicht, jedoch nicht das Laden des Contents behindert oder das Speichermanagement überfordert (siehe unten: Lebenszyklus). Nachdem der Ladevorgang erfolgreich abgeschlossen worden ist, muss der Werbe-Container auf die Größe der Pseudo-Seite gesetzt werden, also auf Fullscreen. Der Nutzer kommt mittels horizontalem Swipe auf die Werbeseite und mittels horizontalem Swipe kann er sich von der Werbeseite wieder auf eine Content-Seite bewegen. Zu dem Zeitpunkt, wenn die Anzeige in den sichtbaren Bereich kommt, wird dem AdServer durch eine entsprechende Methode mitgeteilt, dass die Impression gezählt werden soll. (Siehe unten: Asynchrone Zählung). Ganz wichtig: Eine Fullscreen Anzeige ist kein Overlay oder Interstitial. Das hätte vermarktungstechnisch schwerwiegende Nachteile, weswegen das nicht erlaubt ist. Sollte es hier Probleme geben, bitte unbedingt mit uns Rücksprache halten. Werbemittel für die Anzeige sind 640x920 (auf Smartphones) bzw. 1536x2048 (auf Tablets) groß (oder auch kleiner). Sollte das Display größer sein, wird das Werbemittel zentriert, bei kleineren Displays wird entsprechend kleiner skaliert. Dies passiert alles über das iq digital Template. Das Fullscreen Ad (=Swipe Ad) ist bei Smartphones und 7Zoll Android Tablets auf die Pseudo-Größe 310x480 bzw. 480x310 und bei Tablets auf die Pseudo-Größe 750x1024 bzw. 1024x750 geschaltet. Hier muss die App vor dem Anzeigen des Ads anstelle der Pseudo-Größe die Fullscreen-Werte benutzen und die Größe des Ads entsprechend anpassen. Das Werbetemplate reagiert automatisch und skaliert die Werbung entsprechend. Dafür stellt das Google SDK eine resize Methode zur Verfügung.

Aufgaben des Werbetemplates

Das Werbetemplate ist für die korrekte Skalierung und Darstellung des Werbemittels verantwortlich. Es passt sich bei Orientationchange- oder Resize-Event den neuen Maßen des Werbecontainers an und skaliert die Werbemittel darin entsprechend ihres Seitenverhältnisses. Diese Neuskalierung kann mehrere hundert Millisekunden andauern. Durch die Skalierung können je nach Display am Rand schwarze oder weiße Balken entstehen. Dies passiert immer dann, wenn das Display ein anderes Seitenverhältnis als die Werbemittel hat.

Aufgaben der App

  1. Absenden des Adrequests 1-2 Content-Seiten vor der Platzierung ab, damit der Adserver Zeit genug hat, die Werbung zu liefern.
  2. Dynamisches Erzeugen einer Werbeseite im Seitenfluss rechts neben der zugeordneten Content-Seite
  3. Im Falle einer Buchung: Vergößern des Werbecontainers auf Display-Größe
  4. Ausblenden von App-Header und - Footer
  5. Im Falle keiner Buchung: Entfernen der Werbeseite aus dem Seitenfluss

Ablauf bei einer Buchung im Adserver

  1. App sendet Adrequest an Adserver
  2. Adserver antwortet mit Werbebuchung
  3. App erzeugt dynamisch die Werbeseite
  4. Werbecontainer wird auf die Display-Abmaße aufgezogen
  5. Werbetemplate skaliert Werbemittel in dem Container

Ablauf bei keiner Buchung im Adserver

  1. App sendet Adrequest an Adserver
  2. Adserver antwortet, dass er keine Werbebuchung hat
  3. App erzeugt keine Werbeseite bzw. entfernt eine zuvor erzeugte Werbeseite aus dem Seitenfluss


Beschreibung

Die Werbeplatzierungen sind das Display ausfüllende Anzeigen, die zwischen 2 regulären Seiten in der App angezeigt werden. Grundsätzlich ist die Werbeseite nachfolgend zu ihrer zugeordneten Content-Seite, z.B. Politik/swipe_1 meint, dass zuerst die 1. Politik-Content-Seite angezeigt wird und beim nächsten Swipe die Werbe-Seite erscheint. Sollte keine Werbung gebucht sein, darf die Werbeseite nicht angezeigt werden oder es ist mit Weißräumen zu rechnen. Es ist also eine dynamisch generierte Pseudo-Seite. Aus unserer Sicht wäre es sinnvoller, wenn die Pseudo-Seite initial eingehängt ist und fallweise entfernt wird. Wobei auch der umgekehrte Fall technisch möglich ist. Der Adrequest für diese Platzierung soll dann abgeschickt werden wenn der Ladevorgang sicher abgeschlossen werden kann, bevor der User die Pseudo-Seite erreicht, jedoch nicht das Laden des Contents behindert oder das Speichermanagement überfordert (siehe unten: Lebenszyklus). Nachdem der Ladevorgang erfolgreich abgeschlossen worden ist, muss der Werbe-Container auf die Größe der Pseudo-Seite gesetzt werden, also auf Fullscreen. Der Nutzer kommt mittels horizontalem Swipe auf die Werbeseite und mittels horizontalem Swipe kann er sich von der Werbeseite wieder auf eine Content-Seite bewegen. Zu dem Zeitpunkt, wenn die Anzeige in den sichtbaren Bereich kommt, wird dem AdServer durch eine entsprechende Methode mitgeteilt, dass die Impression gezählt werden soll. (Siehe unten: Asynchrone Zählung). Ganz wichtig: Eine Fullscreen Anzeige ist kein Overlay oder Interstitial. Das hätte vermarktungstechnisch schwerwiegende Nachteile, weswegen das nicht erlaubt ist. Sollte es hier Probleme geben, bitte unbedingt mit uns Rücksprache halten. Werbemittel für die Anzeige sind 640x920 (auf Smartphones) bzw. 1536x2048 (auf Tablets) groß (oder auch kleiner). Sollte das Display größer sein, wird das Werbemittel zentriert, bei kleineren Displays wird entsprechend kleiner skaliert. Dies passiert alles über das iq digital Template. Das Fullscreen Ad (=Swipe Ad) ist bei Smartphones und 7Zoll Android Tablets auf die Pseudo-Größe 310x480 bzw. 480x310 und bei Tablets auf die Pseudo-Größe 750x1024 bzw. 1024x750 geschaltet. Hier muss die App vor dem Anzeigen des Ads anstelle der Pseudo-Größe die Fullscreen-Werte benutzen und die Größe des Ads entsprechend anpassen. Das Werbetemplate reagiert automatisch und skaliert die Werbung entsprechend. Dafür stellt das Google SDK eine resize Methode zur Verfügung.

Anhängen von Key-Value-Paaren:

Bei den Swipe-Anzeigen bitte als Keyword iqadtileFull mitgeben. (siehe oben: Anhängen von Key-Value-Paaren). Zusätzlich wird das Key-Value-Paar tile=1 benötigt (addCustomTargeting("tile","1")).


Lebenszyklus der Swipe-Anzeigen:

Um zu verhindern, dass eine App auf Grund von zu viel Werbung abstürzt, ist es zu erwarten, dass die App eine Anzeige aus Gründen des Speichermanagements auf dem Arbeitsspeicher entfernt. Hier muss gewährleistet sein, dass die dem User am nächsten liegende Anzeige vorgeladen bleibt. Ebenfalls muss einem Nutzer-Verhalten Rechnung getragen werden, bei dem er sich nicht streng linear durch die Abfolge der Seiten bewegt, sondern auch rückwärts swipen kann, in Richtung einer bereits gesehenen Anzeige. Diese muss dann wiederrum vorgeladen sein, und falls bereits aus dem Speicher entfernt, neu angefordert werden.

Wichtige Klassen für das Swipe Ad (iOS und Android):

Wie beim Preloading Ad, aber zusätzlich: Der Container für die Werbemittel: https://developers.google.com/android/reference/com/google/android/gms/ads/doubleclick/PublisherAdView https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/api/reference/Classes/DFPBannerView Zum Setzen der Größe: https://developers.google.com/android/reference/com/google/android/gms/ads/AdSize https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/api/reference/Structs/GADAdSize

Asynchrone Zählung für Fullscreen/Swipe Anzeigen:

Das Google SDK bietet Methoden für die manuelle Impressionzählung. Dabei kann das Ad abgerufen werden und die Impressionzählung verzögert werden, bis zu dem Zeitpunkt, den die App dafür vorgibt. Dieser Zeitpunkt ist dann gekommen, wenn mindestens 1Pixel der Werbung auf dem Screen zu sehen ist, also sobald die Werbeanzeige in den sichtbaren Bereich geswiped wird. https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/banner#manual_impression_counting

https://developers.google.com/mobile-ads-sdk/docs/dfp/android/banner#multiple_ad_sizes unter iOS: https://developers.google.com/mobile-ads-sdk/docs/dfp/ios/banner#multiple_ad_sizes  

Beschreibung

Die Werbeplatzierungen sind Banner-Platzierungen innerhalb der Content-Seite, die üblicherweise 320px Breite und eine bestimmte Höhe einnehmen. Sollte keine Werbung gebucht sein, wird die Platzierung ausgeblendet, es sollte kein Weißraum entstehen. Die Adrequests für diese Platzierungen sollten initial beim Pagerequest erfolgen. Bei sehr langen Seiten, ist es auch möglich weiter unten liegende Banner Platzierungen erst zu laden, wenn der untere Content generiert wird. Jedoch sollte dabei immer berücksichtigt werden, dass das Ad genug Zeit hat, rechtzeitig angezeigt zu werden. Für Banner-Platzierungen benutzen wir Pseudo-größen (z.B. 310x1, 310x4, 310x8 usw.). Damit das Banner in der korrekten Größe dargestellt wird, rufen die iq digital Templates ein bestimmtes Event auf. Dazu stellt die iq digital ein EventHandler-Klasse für Android zur Verfügung, die in die App integriert werden muss. Für iOS muss diese Klasse von den Appentwicklern portiert werden. Die EventHandler-Klasse benutzt eine spezielle Syntax für ein resize-Event. Die App muss bei Erhalt des Events dann entsprechend der Logik die Größe des Ad entsprechend ändern. Die App Events, die von der EventHandler-Klasse behandelt werden müssen, sind im Anhang A dokumentiert. Für Android gibt es mit der PublisherAdAppEventListener.java eine Vorlage, die nur noch um appspezifischen Code erweitert werden muss.

Anhängen von Key-Value-Paaren:

Bei den Werbeanzeigen muss die App entsprechend der Platzierung ein Keyword mitgeben, z.B. iqadtile1 für die Banner-Platzierung ganz oben, analog zu den MEW Platzierungen. (siehe oben: Anhängen von 1.2 Key-Value-Paaren). Zusätzlich werden Key-Value-Paar tile1 benötigt addCustomTargeting("tile","1") Für die übrigen Platzierungen ist analog zu verfahren.

Werbemittelkennzeichnung:

Der Mandant muss über jeder Werbeplatzierung eine Werbemittelkennzeichnung einbauen. Hier empfehlen wir eine Kennzeichnung analog zur MEW-Werbekennzeichnung, z.B. das Wort "Anzeige" in vergleichbarer Schriftgröße und -farbe. Damit die Werbekennzeichnung nicht sichtbar ist, falls keine Werbung für eine Platzierung gebucht ist, muss die Werbekennzeichnung ausgeblendet werden können. Hierzu stellt die oben beschriebene EventHandler-Klasse der iq digital ein spezielles noad-Event zur Verfügung. Der Mandant muss hier nur die Logik zum Ausblenden der Kennzeichnung einbauen. Das iq digital Template ruft im Falle einer Leer-Ausspielung dieses Event auf und die App blendet die Werbeplatzierung samt der Kennzeichnung aus. Eine Kennzeichnung über der Platzierung durch die iq digital ist nicht möglich. Eine Beschreibung des noad-Event befindet sich im Anhang A.  

Anhang

Dokumentation der iq digital App Events

Die App Events bestehen aus dem Namen und einem "data"-String setsize – Event Das setsize-Event wird von den Werbetemplates der iq digital aufgerufen, um die Größe des Adviews der Werbeplatzierung zu verändern. Dabei werden Größenänderung mit Animation und sofortige Größenänderungen ohne Animation unterschieden. Der "data"-String kann folgende Formate haben: 1. "width:height" - für eine sofortige Änderung der Größe ohne Animation 2. "width:height:duration:steps" - für eine Änderung der Größe mit Animation Parameter: Die Parameter werden mit einem Doppelpunkt voneinander getrennt. width - Die neue Breite des Adviews in Pixel (Device-Independent-Pixel) als ganze Zahl. Ausnahme: Für eine Anpassung auf die maximal verfügbare Breite wird der Wert max verwendet height – Die neue Höhe des Adviews in Pixel (Device-Independent-Pixel) als ganze Zahl. Ausnahme: Für eine Anpassung auf die maximal verfügbare Höhe wird der Wert max verwendet duration – Die Gesamtdauer der Animation der Größenanpassung des Adviews in Millisekunden als ganze Zahl steps – Die Anzahl der Schritte der Größenanpassung des Adviews, d.h. die Differenz der neuen Größe von der alten Größe wird in so viele Schritte unterteilt und die Größenanpassung schrittweise innerhalb der duration durchgeführt.

Beispielaufrufe: "setsize","320:80" Adview bekommt die neue Größe 320x80 Pixel "setsize","320:240" Adview bekommt die neue Größe 320x240 Pixel "setsize","max:160" Adview wird auf die maximal verfügbare Breite und eine Höhe von 160 Pixel angepasst "setsize","max:max" Adview wird auf die maximal verfügbare Breite und die maximal verfügbare Höhe angepasst "setsize","320:80:500:10" Adview bekommt die neue Größe 320x80 Pixel. Die Änderung erfolgt in 10 Schritten und dauert insgesamt 500ms "setsize","320:240:1000:20" Adview bekommt die neue Größe 320x240 Pixel. Die Änderung erfolgt in 20 Schritten und dauert insgesamt 1000ms "setsize","max:160:200:2" Adview wird auf die maximal verfügbare Breite und eine Höhe von 160 Pixel angepasst . Die Änderung erfolgt in 2 Schritten und dauert insgesamt 200ms "setsize","max:max:400:5" Adview wird auf die maximal verfügbare Breite und die maximal verfügbare Höhe angepasst. Die Änderung erfolgt in 5 Schritten und dauert insgesamt 400ms noad – Event Das noad-Event wird von den Werbetemplates der iq digital aufgerufen, um der App zu signalisieren, dass für die Platzierung keine Buchung vorliegt und die App die Werbeplatzierung und die zugehörige Anzeigenkennzeichnung entfernen soll. Der "data"-String hat für dieses Event keine Bedeutung und kann ignoriert werden.

log – Event Das log-Event wird von den Werbetemplates der iq digital aufgerufen, um eine Nachricht in das App-Log zu schreiben. Dieses dient zu Debug Zwecken. Der "data"-String enthält die Nachricht, die die App in das Log eintragen soll.

Abgerufen von „http://docs.iqd-ao.de/de/index.php?title=Einbau_des_Google_Mobile_Ads_SDK&oldid=83“