Documentation

Integration of the Google Mobile Ads SDK: Difference between revisions

← Older edit
No edit summary
 
(18 intermediate revisions by the same user not shown)
Line 59: Line 59:
:;platform:The operating system, in other words ''ios'' or ''android''
:;platform:The operating system, in other words ''ios'' or ''android''
:;devicetype:The device type, in other words ''phone'' or ''tablet''
:;devicetype:The device type, in other words ''phone'' or ''tablet''
;level2:This is the designation of a section of the app, e.g. politik (politics)
;level2:This is the designation of a section of the app or the homepage, e.g. ''politik'', ''openingpage''
;level3 (etc.):This is the designation for a sub-section. For example: in the case of politik as level2 ausland (foreign) would be a sub-section for level3. level4 and higher are further, deeper branches of the app and are not usually created as ad units. These types of pages would then be marketed via the supraordinate level3. Example: a page politik/ausland/usa is too specific to be marketed individually. In such a case, it is a good idea that it is only tagged down to level3, in other words as politik/ausland.
;level3 (etc.):This is the designation for a sub-section. For example: in the case of politik as level2 ausland (foreign) would be a sub-section for level3. level4 and higher are further, deeper branches of the app and are not usually created as ad units. These types of pages would then be marketed via the supraordinate level3. Example: a page politik/ausland/usa is too specific to be marketed individually. In such a case, it is a good idea that it is only tagged down to level3, in other words as politik/ausland.
;pagetype:In apps with banner ads (e.g. news apps), seitentyp designates the different page types – in other words, whether the page is, for example, an overview, article or photo gallery page. Standard values here are homepage, index, artikel, bildgal. In apps with fullscreen ads (e.g. ePaper or newspaper apps), seitentyp refers to the different ad positions within the section – in other words, whether they are the first, second or third swipe ad, for example. Standard values are openingpage, swipe_1, swipe_2, swipe_3 etc.
;pagetype:In apps with banner ads (e.g. news apps), seitentyp designates the different page types – in other words, whether the page is, for example, an overview, article or photo gallery page. Standard values here are homepage, index, artikel, bildgal. In apps with fullscreen ads (e.g. ePaper or newspaper apps), seitentyp refers to the different ad positions within the section – in other words, whether they are the first, second or third swipe ad, for example. Standard values are swipe_1, swipe_2, swipe_3 etc.


====Example for the fictitious Rheinischer Kurier news app with banner ads:====
====Example for the fictitious Rheinischer Kurier news app with banner ads:====
Line 76: Line 76:
*/183/Rheinischer_Kurier_epaper_app_ios_tablet
*/183/Rheinischer_Kurier_epaper_app_ios_tablet
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/preloading_ad
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/preloading_ad
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/openingpage
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/openingpage/swipe_1
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/politik/swipe_1
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/politik/swipe_1
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/politik/swipe_2
*/183/Rheinischer_Kurier_epaper_app_ios_tablet/politik/swipe_2
Line 126: Line 126:
*https://developers.google.com/ad-manager/mobile-ads-sdk/ios/targeting#custom_targeting
*https://developers.google.com/ad-manager/mobile-ads-sdk/ios/targeting#custom_targeting
*https://developers.google.com/ad-manager/mobile-ads-sdk/android/targeting#custom_targeting
*https://developers.google.com/ad-manager/mobile-ads-sdk/android/targeting#custom_targeting
===Content-Url parameter in the adrequest===
In order for programmatic partners (e.g. Adexchange, Headerbidding or Backfill) to bid as high as possible for an ad placement, this app ad placement must be told which stationary website it actually belongs to. This is done via the content-url parameter in the adrequest. The URL of the web page that matches the content in the app as closely as possible must be passed here as the value. Example: An app article should link to its stationary web article in the content-url parameter, an app home page to the home page, etc. The GMA SDK has a setContentUrl function for this purpose. This is described in more detail here:
*https://developers.google.com/ad-manager/mobile-ads-sdk/ios/targeting?hl=de#content_url
*https://developers.google.com/ad-manager/mobile-ads-sdk/android/targeting?hl=de#content_url
===Political advertising in native apps===
Political campaigns require consent from the user. In order for the ad server to take this into account correctly, it needs information from the app. The exact workflow works as follows:
====Workflow====
#The user decides in the CMP whether to give consent for political advertising
#The app evaluates the consent and checks whether consent has been given for political advertising
#If consent has been given, the app adds the keyword '''''political_ad''''' to the '''''kw''''' keywords for each ad request (see [[#Keywords (attachment of key-value pairs)]]).
#The ad server sees the keyword '''''political_ad''''' in the ad request and now has the option of delivering a political campaign targeted to that keyword (however, this is not mandatory; it can also deliver other campaigns).
#When an ad server plays a political campaign, a creative is delivered to the app that contains an additional setting in the template. This causes the creative to inform the app that the advertising slot in question actually contains a political campaign and that the app should respond by changing the ad label. The message is sent to the app via a political_ad event (see [[#Documentation of the iq digital app events]]).
#The app receives the '''''political_ad''''' event and can respond to it. iqdigital recommends that the ad label above the affected ad slot be changed to '''''Politische Anzeige''''' and that there be a link to the Political Ad Transparency URL for the campaign (which is passed in the event). '''Important''': The responsibility for whether and how the app responds to the '''''political_ad''''' event lies with the publisher and the app.
====App tasks (publisher tasks)====
*The app evaluates the consent string and checks whether the user has given consent for political advertising.
*If consent for political advertising has been given, the app adds the keyword '''''political_ad''''' to CustomTargeting (to key '''''kw''''').
*When the app receives a '''''political_ad''''' event through a creative, it should respond to it, for example by changing the ad label to '''''Politische Anzeige''''', as described above. If a URL is also passed as a data-String in the event, a link with the URL and the text '''''(mehr dazu)''''' should appear next to the ad label '''''Politische Anzeige'''''. Clicking on the link then opens the URL, where the user can find further information about the type of campaign.
====Tasks of the advertising template====
*A political campaign must be configured accordingly in the ad server. This is done via settings in the advertising template. This involves marking that the creative belongs to a political campaign and setting the PoliticalAdTransparencyUrl (for the "(mehr dazu)" link).
*The advertising template internally evaluates whether it is a political ad.
*In the case of a political advertisement, it sends an event to the app with the key political_ad and the set PoliticalAdTransparencyUrl as the "data" string.
====Example====
Attached is an example of a test campaign that has been marked as a political ad.
[[File:Political_Ad_Testkampagne.png|800px|thumbnail|Display of a political campaign from the web (right side of the image)]]
====Test placement====
The following keywords (separated by commas) can be set in the debug Easter egg:
<pre>iqdtests,political_ad_test</pre>
This will run an orange test ad on iqadtile1, iqadtile3 and/or iqadtile4 with the text "POLITICAL AD Test 320x320." However, this will only appear if the app transmits the keyword political_ad after evaluating consent in accordance with the instructions for political advertising.


===Debugging===
===Debugging===
Line 219: Line 254:
}}
}}


==Fullscreen Anzeigen (auch Swipe Anzeigen oder Swipe-Ads genannt)==
==Fullscreen Ads (also called swipe ads)==
{{SDKAppInfo
{{SDKAppInfo
|info=
|info=
Die Werbeplatzierung ist eine Display ausfüllende Anzeigen, die zwischen zwei regulären Content-Seiten in der App angezeigt wird. Sie lässt sich horizontal wie die übrigen Content-Seiten swipen und wird von keinen Teilen der App (wie App-Header oder -Footer) überlagert. Sollte der Nutzer ein Orientationchange-Event erzeugen, passt sich die Anzeige dem neuen Seitenverhältnis an.
The ad position is a display-filling ad displayed between two regular content pages in the app. It can be horizontally swiped like the other content pages and is not overlaid by any parts of the app (like the app header or footer). If the user generates an orientation change event, the ad adapts to the new aspect ratio.


[[Datei:Fullscreen Ad 1.png|x300px]]
[[Datei:Fullscreen Ad 1.png|x300px]]
[[Datei:Fullscreen Ad 2.png|300px]]
[[Datei:Fullscreen Ad 2.png|300px]]
|position=
|position=
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
The position is dynamically embedded between two content pages. The ad position is always on the right next to the page assigned to it in the content (e.g. Politik/swipe_1 means that the first politics content page is displayed first and that the advertising page appears with the next swipe).  
|template=
|template=
*skaliert Werbemittel bei Beibehaltung des Seitenverhältnisses entsprechend der Abmaße des Werbecontainers
*Scales ads while retaining the aspect ratio in line with the dimensions of the ad container.
*positioniert und zentriert das Werbemittel
*Positions and centres the ad.
*bei Orientationchange- oder Resize-Event: skaliert die Werbemittel enstprechend der neuen Maße. Dies kann mehrere hundert Millisekunden dauern, bis alle neuen Maße feststehen und vom Webviewbrowser zur Verfügung gestellt werden.
*In the case of orientation change or resize event: scales the ads in line with the new dimensions. It can take several hundred milliseconds until all new dimensions are determined and can be made available by the webview browser.
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.
Depending on the display, scaling can result in black or white bars at the edges. This always happens when the display has a different aspect ratio than the ads.
|app=
|app=
*sendet das Adrequest 1-2 Content-Seiten vor der Platzierung ab, damit der Adserver Zeit genug hat, die Werbung zu liefern
*Sends the ad request 1-2 content pages before the position so that the ad server has enough time to serve the ad.
*erzeugt dynamisch eine Werbeseite im Seitenfluss rechts neben der zugeordneten Content-Seite
*Dynamically generates an ad page in the page flow on the right next to the assigned content page.
*im Falle einer Buchung: vergößert den Werbecontainers auf Display-Größe
*In the event of a booking: upsizes the ad container to display size.
*blendet App-Header und -Footer aus (falls erforderlich)
*Blanks app header and footer (if necessary)
*bei Orientationchange- oder Resize-Event: passt die Werbeseite und den Werbecontainer an die neuen Display-Maße an
*In the case of orientation change or resize event: adapts the ad page and the ad container to the new display dimensions.
*im Falle '''keiner''' Buchung: entfernt die Werbeseite aus dem Seitenfluss
*In the case of no booking: removes the ad page from the page flow.
|workflowad=
|workflowad=
#App sendet Adrequest an Adserver
#The app sends an ad request to the ad server.
#Adserver antwortet mit Werbebuchung
#The ad server responds with an ad booking.
#App erzeugt dynamisch die Werbeseite
#The app dynamically generates the ad page.
#Werbecontainer wird auf die Display-Abmaße aufgezogen
#The ad container is upsized to the display dimensions.
#Werbetemplate skaliert Werbemittel in dem Container
#The ad template scales the ad in the container.
|workflownoad=
|workflownoad=
#App sendet Adrequest an Adserver
#The app sends an ad request to the ad server.
#Adserver antwortet, dass er keine Werbebuchung hat
#The ad server responds that it has no ad booking.
#App erzeugt '''keine''' Werbeseite bzw. entfernt eine zuvor erzeugte Werbeseite aus dem Seitenfluss
#The app does not generate an ad page or removes a previously generated ad page from the page flow.
|creativesizes=
|creativesizes=
;Smartphone:310x480 bzw. 480x310
;Smartphone:310x480 and 480x310
;Tablet:750x1024 bzw. 1024x750<br />(bei Android auch zusätzlich: 310x480 bzw. 480x310)
;Tablet:750x1024 and 1024x750<br />(with Android also additionally: 310x480 and 480x310)
{{Warnung|text=Die Creativesizes sind Pseudogrößen, sie entsprechen nicht den tatsächlichen Abmaßen des Werbemittels.}}
{{Warnung|text=The creative sizes are pseudo-sizes; they do not correspond to the actual dimensions of the ad.}}
|keywords=
|keywords=
;kw:iqadtileFull
;kw:iqadtileFull
Line 262: Line 297:
}}
}}


==Banner-Anzeigen==
==Banner ads==
{{SDKAppInfo
{{SDKAppInfo
|info=
|info=
Die Werbeplatzierung ist ein Banner innerhalb einer Content-Seite. Je nach Werbeform kann diese Anzeige mehr oder weniger Interaktivität für den Endnutzer besitzen. Sie kann anmiert oder eine komplexe HTML-Anzeige sein. Es ist auch möglich dass die Anzeige durch bestimmte Ereignisse sich in der Größe verändert.
The ad position is a banner within a content page. Depending on the ad format, this ad may permit more or less interactivity for the end user. It may be animated or may be a complex HTML ad. It is also possible that the ad may change in size due to certain events.


[[Datei:Mobile High Impact Ad.png|x300px]]
[[Datei:Mobile High Impact Ad.png|x300px]]
|position=
|position=
Die Platzierung ist zwischen Content-Elemente einer Seite platziert und erfordert eine Anzeigenkennzeichnung "Anzeige" oberhalb der Platzierung. Üblicherweise befinden sich mehrere Platzierungen innerhalb einer Seite.
The position is between content elements of a page and requires labelling as “Anzeige” (Advertisement) above the position. There are generally multiple positions within a page.
|template=
|template=
*kümmert sich um die Funktionalität, welche je nach Werbeform simpel oder komplex sein kann.
*Handles the functionality, which may be simple or complex depending on the ad format.
|app=
|app=
*sendet die Adrequests für alle Platzierungen einer Seite
*Sends the ad requests for all positions on a page.
*baut für jede Platzierung eine Anzeigenkennzeichnung "Anzeige" oberhalb der Platzierung ein
*Integrates an ad label “Advertisement” above the position for each position.
*erstellt den Werbecontainer mit Größe, welche in der Antwort vom Andserver auf das Adrequest mitgeliefert wird
*Creates the ad container with a size that is included in the response from the ad server to the ad request.
*lauscht mit dem EventListener auf mögliche setsize- oder noad-Events und verändert den Werbecontainer entsprechend.
*Listens with the EventListener for possible setsize or noad events and changes the ad container accordingly.
*im Falle einer Ausbuchung:
*In the event of an outbooking:
**empfängt sie ein setsize-Event muss sie die Werbeplatzierung und den Werbecontainer an die neue Größe anpassen, sofern sich diese von der aktuellen Größe unterscheidet
**If it receives a setsize event, it must adapt the ad position and the ad container to the new size where it differs from the current size.
**empfängt sie ein noad-Event, muss sie die Werbeplatzierung und die zugehörige Anzeigenkennzeichnung komplett entfernen bzw. ausblenden
**If it receives a noad event, it must completely remove or blank the ad position and the corresponding ad label.
|workflowad=
|workflowad=
#App sendet Adrequest an Adserver
#The app sends an ad request to the ad server.
#Adserver antwortet mit Werbebuchung
#The ad server responds with an ad booking.
#App erzeugt Werbecontainer mit der Größe, die in der Response des Adservers enthalten ist
#The app generates the ad container with the size contained in the response of the ad server.
#eventuell muss der Werbecontainer auf Grund eines setsize-Events angepasst werden
#It may be necessary to adapt the ad container due to a setsize event.
|workflownoad=
|workflownoad=
#App sendet Adrequest an Adserver
#The app sends an ad request to the ad server.
#Adserver antwortet mit Ausbuchung als Werbebuchung
#The ad server responds with an outbooking as ad booking.
#App empfängt eine Response mit der Größe 99x1 und erhält kurze Zeit später ein noad-Event
#The app receives a response with the size 99x1 and a short time later a noad event.
#App blendet Werbeplatzierung und Anzeigenkennzeichnung bis zum nächsten Pagerequest aus
#The app blanks the ad position and ad labelling until the next page request.
|creativesizes=
|creativesizes=
320x50, 320x53, 320x80, 320x106, 320x160, 320x320, 320x416, 320x460, 300x50, 300x75, 300x100, 300x150, 300x200, 300x250, 300x600
320x50, 320x53, 320x80, 320x106, 320x160, 320x320, 320x416, 320x460, 300x50, 300x75, 300x100, 300x150, 300x200, 300x250, 300x600
Weitere Größen sind möglich. Je nach Platzierung wird nur ein Auszug der Größenliste im Adrequest verwendet. Eine genaue Zuordnung erfolgt in einem separaten Dokument.
Other sizes are possible. Depending on the
position, only an excerpt from the size list is used in the ad request. Exact assignment then takes place in a separate document.
 
|keywords=
|keywords=
;kw:nospa, enozqi, digtransform, iqadtileX*
;kw:nospa, enozqi, digtransform, iqadtileX*
;tile:X*
;tile:X*
X entspricht dabei der Nummer der Platzierung, z.B. iqadtile1, iqadtile3, iqadtile4, iqadtile99, iqadtile8
X corresponds to the number of the position, e.g. iqadtile1, iqadtile3, iqadtile4, iqadtile99, iqadtile8.
|links=
|links=
;iOS:https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner
;iOS:https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner
Line 302: Line 339:
}}
}}


==Dokumentation der iq digital App Events==
==Documentation of the iq digital app events==
Die Werbetemplates der iq digital senden in bestimmten Situationen Events an die App. Die App muss auf diese Events reagieren und gemäß der folgenden Spezifikation den Werbecontainer verändern. Die App Events bestehen dabei immer aus dem Namen und einem "data"-String.
In certain situations, the ad templates of iq digital send events to the app. The app must react to these events and change the ad container in line with the following specification. The app events always comprise the name and one "data" string.


===Wichtige Links in der GMA SDK Dokumentation===
===Important links in the GMA SDK documentation===
*[https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner#app_events GMA SDK iOS App Events]
*[https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner#app_events GMA SDK iOS App Events]
*[https://developers.google.com/ad-manager/mobile-ads-sdk/android/banner#app_events GMA SDK Android App Events]
*[https://developers.google.com/ad-manager/mobile-ads-sdk/android/banner#app_events GMA SDK Android App Events]


===setsize – Event===
===setsize event===
Das setsize-Event wird von den Werbetemplates der iq digital aufgerufen, um die Größe des Adviews der Werbeplatzierung zu verändern.
The setsize event is called by the ad templates of iq digital to change the size of the ad view of the ad position. The "data" string has the format "width:height" for an immediate change of size.
Der "data"-String hat das Format '''"width:height"''' für eine sofortige Änderung der Größe.
 
=====Parameters=====
The parameters are separated from one another with a colon.
;width:The new width of the ad view in pixels (device-independent pixels) as a whole number.
;height:The new height of the ad view in pixels (device-independent pixels) as a whole number.
{{Warnung|text=Exception: the value max is used for adaptation to the maximum available width or height.}}
 
Call examples:
;<nowiki>"setsize","320:80"</nowiki>:Ad view is given the new size of 320x80 pixels.
;<nowiki>"setsize","320:240"</nowiki>:Ad view is given the new size of 320x240 pixels.
;<nowiki>"setsize","max:160"</nowiki>:Ad view is adjusted to the maximum available width and a height of 160 pixels.
;<nowiki>"setsize","max:max"</nowiki>:Ad view is adjusted to the maximum available width and the maximum available height.
 
===noad event===
The noad event is called by the ad templates of iq digital to signal to the app that there is no booking for the position and that the app should remove the ad position '''and the corresponding ad label'''.


=====Parameter=====
The "data" string has no meaning for this event and can be ignored. Since Google's AppEventListener interface has a @NonNull annotation for data, the noad event simply passes the value "noad" for data, since the empty string is converted as null by Google.
Die Parameter werden mit einem Doppelpunkt von einander getrennt.
;width:Die neue Breite des Adviews in Pixel  (Device-Independent-Pixel) als ganze Zahl.
;height:Die neue Höhe des Adviews in Pixel  (Device-Independent-Pixel) als ganze Zahl.
{{Warnung|text=Ausnahme: Für eine Anpassung auf die maximal verfügbare Breite oder Höhe wird der Wert '''max''' verwendet.}}


Beispielaufrufe:
===policial_ad event===
;<nowiki>"setsize","320:80"</nowiki>:Adview bekommt die neue Größe 320x80 Pixel
The policial_ad event is called by iq digital's advertising templates to signal to the app that a political campaign exists on this placement and that it should respond to it (see [[#Political advertising in native apps]]).
;<nowiki>"setsize","320:240"</nowiki>:Adview bekommt die neue Größe 320x240 Pixel
;<nowiki>"setsize","max:160"</nowiki>:Adview wird auf die maximal verfügbare Breite und eine Höhe von 160 Pixel angepasst
;<nowiki>"setsize","max:max"</nowiki>:Adview wird auf die maximal verfügbare Breite und die maximal verfügbare Höhe angepasst


===noad – Event===
The "data" string contains the PolticialAdTransparencyUrl, provided it has been defined in the campaign in the ad server.
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.
====Example call:====
;<nowiki>"policial_ad","https://www.diesisteinekampagne.de/transparency.html"</nowiki>:The app should use "Politische Anzeige [https://www.diesisteinekampagne.de/transparency.html (mehr dazu)]" as the ad label for the placement, as recommended


[[Kategorie:Ad Technology]][[Kategorie:APP]]
[[Kategorie:Ad Technology]][[Kategorie:APP]]
[[en:Integration of the Google Mobile Ads SDK]]
[[de:Einbau des Google Mobile Ads SDK]]
Retrieved from "http://docs.iqd-ao.de/en/index.php?title=Integration_of_the_Google_Mobile_Ads_SDK"