User Guide
ADTECH Mobile for App Developers
ADTECH GmbH
2012-12-18 Page 2 of 216
Table of Contents
About this Document ... 6
Chapter 1
Framework and Technology
7
Getting Started in ADTECH Mobile ... 8ADTECH Display versus ADTECH Mobile ... 9
ADTECH Mobile Feature List ... 10
Mobile Ad Request ... 12
Device Screen Size Categories ... 13
MMA Mobile Web Banner Ad Sizes ... 14
Keyword, Key Value and Alias ... 15
Request URLs with Keyword, Key Value and Alias ... 17
HTTP Header Information ... 18
Mediation ... 19
More than One Mediation Partner ... 21
Postclick Tracking Beacon Tags ... 22
Chapter 2
ADTECH Mobile SDK
24
2.1 General Information About the ADTECH Mobile SDK ... 25ADTECH Mobile SDK Release Notes ... 26
Purpose and Contents of the ADTECH Mobile SDK ... 27
Responsibilities of the App Developer ... 28
Compliance with Advertising Standards ... 29
MRAID Compliance ... 30
ORMMA Compliance ... 32
VAST Compliance ... 33
The ADTECH Mobile SDK Features and Properties ... 34
ADTECH Mobile SDK Feature Matrix for Different Platforms ... 36
Placement Configuration for the ADTECH Mobile SDK ... 38
Tracking Unique Devices with the Mobile SDK ... 44
Logging the ADTECH Mobile SDK Activity in the Console ... 45
Caching and Offline Display ... 46
Video Ads in the ADTECH Mobile SDK ... 48
Mediation in the ADTECH Mobile SDK ... 51
2.2 ADTECH Mobile SDK: iOS ... 52
2.2.1 Getting Started with the ADTECH Mobile SDK for iOS ... 53
How to Integrate the ADTECH Mobile SDK into Your iOS App ... 54
How to Update the ADTECH Mobile SDK to a Newer Version (iOS) ... 59
ADTECH Mobile SDK Release Notes (iOS) ... 61
2.2.2 How to Use the Mobile SDK in iOS ... 63
2012-12-18 Page 3 of 216
How to Add a Banner Entirely from Code (iOS) ... 68
How to Add an Interstitial (iOS) ... 70
Banner and Interstitial Configuration (iOS) ... 72
How to Use Video Ads (iOS) ... 74
How to Set the SDK Log Level (iOS) ... 76
How to Add Additional Key Value Parameters to the Ad Configuration (iOS) ... 77
How to Localize Messages Presented from the SDK (iOS) ... 79
What You Need to Know for Your iOS App to Work Well With the SDK ... 80
2.2.3 The Public Interface (iOS) ... 82
iOS Class: ATBannerView ... 83
iOS Class: ATInterstitialView ... 85
iOS Class: ATMoviePlayerController ... 87
iOS Class: ATBaseConfiguration ... 88
iOS Class: ATAdConfiguration ... 92
iOS Class: ATVideoAdConfiguration ... 94
iOS Class: ATVideoAdOverlay ... 96
iOS Protocol: ATBannerViewDelegate ... 98
iOS Protocol: ATInterstitialViewDelegate ... 100
iOS Enums ... 102
iOS Constants ... 104
2.2.4 How to Use Mediation for Third Party Advertisement SDKs in iOS ... 105
How to Add a Third Party SDK (iOS) ... 106
Supported Third Party SDK’s (iOS) ... 107
AdMob Configuration in the ADTECH Mobile SDK (iOS) ... 108
iAd Configuration in the ADTECH Mobile SDK (iOS) ... 109
Millennial Configuration in the ADTECH Mobile SDK (iOS) ... 110
Greystripe Configuration in the ADTECH Mobile SDK (iOS) ... 111
Vdopia Configuration in the ADTECH Mobile SDK (iOS) ... 112
2.3 ADTECH Mobile SDK: Android ... 113
2.3.1 Getting Started with the ADTECH Mobile SDK for Android ... 114
How to Integrate the ADTECH Mobile SDK into Your Android App ... 115
Permissions for the Mobile SDK (Android) ... 117
ADTECH Mobile SDK Release Notes and API Changelog (Android) ... 119
2.3.2 How to Use the Mobile SDK in Android ... 121
How to Add a Banner as a Resource (Android) ... 122
How to Add a Banner Dynamically (Android) ... 125
How to Manage the Banner Life Cycle (Android) ... 126
How to Add an Interstitial (Android) ... 127
How to Manage the Interstitial Life Cyle (Android) ... 129
Ad Container Restrictions (Android) ... 130
How to Set the Visibility of the Container (Android) ... 131
How to Configure an Ad (Android) ... 132
2012-12-18 Page 4 of 216
How to Use Direct Landing Page URLs (Android) ... 135
How to Use Video Ads (Android) ... 136
How to Set the SDK Log Level (Android) ... 139
How to Add Additional Key Value Parameters to the Ad Configuration (Android) ... 140
How to Localize Messages Presented from the SDK (Android) ... 141
What You Need to Know for Your Android App to Work Well With the SDK ... 142
2.3.3 The Public Interface (Android) ... 143
Android Classes ... 144
2.3.4 How to Use Mediation for Third Party Advertisement SDKs in Android ... 146
How to Add a Third Party SDK (Android) ... 147
Supported Third Party SDK’s (Android) ... 148
AdMob Configuration in the ADTECH Mobile SDK (Android) ... 149
Millennial Configuration in the ADTECH Mobile SDK (Android) ... 151
Greystripe Configuration in the ADTECH Mobile SDK (Android) ... 154
Vdopia Configuration in the ADTECH Mobile SDK (Android) ... 156
2.4 ADTECH Mobile SDK: Windows Phone ... 157
2.5 How to Use the Mobile SDK in Windows Phone ... 158
How to Integrate the ADTECH Mobile SDK into Your Windows Phone Application ... 159
Banner and Interstitial Default Configuration (Windows Phone) ... 161
How to Add a Banner from XAML/Design Editor (Windows Phone) ... 163
How to Add a Banner Entirely from Code (Windows Phone) ... 166
How to Add an Interstitial Ad from XAML (Windows Phone) ... 167
How to Add an Interstitial Entirely from Code (Windows Phone) ... 170
How to Add Additional Key-value Parameters to the Ad Configuration (Windows Phone)... 172
2.6 The Public Interface (Windows Phone) ... 173
Windows Phone Class: BaseAdtechControl ... 174
Windows Phone Class: AdtechBannerControl ... 175
Windows Phone Class: AdtechInterstitialControl ... 176
Windows Phone Enums ... 177
2.7 Marketplace Submission Guidelines (Windows Phone) ... 178
Application Policies for the Windows Phone Marketplace ... 179
2.8 ADTECH Mobile SDK: Windows 8 ... 180
2.8.1 Getting Started with the ADTECH Mobile SDK (Windows 8) ... 181
How to Integrate the ADTECH Mobile SDK into Your Windows 8 Store Application ... 182
ADTECH Mobile SDK Release Notes (Windows 8) ... 185
2.9 How to Use the Mobile SDK in Windows 8 ... 186
Banner and Interstitial Default Configuration (Windows 8) ... 187
How to Add a Banner from XAML/Design Editor (Windows 8) ... 188
How to Add a Banner Entirely from Code (Windows 8) ... 191
How to Add an Interstitial Ad from XAML (Windows Phone) ... 192
How to Add an Interstitial Entirely from Code (Windows 8) ... 195
2012-12-18 Page 5 of 216
2.10 The Public Interface (Windows 8) ... 198
Windows 8 Class: BaseAdtechControl ... 199
Windows 8 Class: AdtechBannerControl ... 200
Windows 8 Class: AdtechInterstitialControl ... 201
Windows 8 Enums ... 202
2.11 Windows Store Submission Guidelines (Windows 8)... 203
Application Policies for the Windows 8 Store ... 204
2.12 ADTECH Mobile SDK Limitations ... 205
Platform Specific Mobile SDK Limitations ... 206
MRAID 1.0 SDK Limitations ... 208
MRAID 2.0 SDK Limitations ... 209
ORMMA Level 2 SDK Limitations ... 212
Caching and Offline Display SDK Limitations ... 213
VAST SDK Limitations ... 214
Chapter 3
Glossary
216
2012-12-18 Page 6 of 216
About this Document
This document describes ADTECH Mobile, the ad serving solution for mobile devices. ADTECH Mobile, ADTECH’s new integrated mobile solution, makes mobile advertising much easier, more efficient and successful. ADTECH Mobile allows you to book mobile campaigns as easy as traditional display campaigns.
All information from the ADTECH user guides is proprietary and to be treated as strict-ly confidential. Data is exclusivestrict-ly destined for the exclusive and internal use of the ADTECH customer. Any use, transmission, provision of access to third parties, circula-tion or any other utilizacircula-tion of the data or of informacircula-tion provided, other than con-tractual, is strictly prohibited.
ADTECH GmbH Robert-Bosch-Str. 32 D-63303 Dreieich GERMANY Phone: +49 6103 5715-0 Fax: +49 6103 5715-111 E-Mail: [email protected] URL: http://www.adtech.de/ About this document
Copyright and confidentiality
2012-12-18 Page 7 of 216
Chapter 1
Framework and Technology
Topic Page
Getting Started in ADTECH Mobile ... 8
ADTECH Display versus ADTECH Mobile ... 9
ADTECH Mobile Feature List ... 10
Mobile Ad Request ... 12
Device Screen Size Categories ... 13
MMA Mobile Web Banner Ad Sizes... 14
Keyword, Key Value and Alias ... 15
Request URLs with Keyword, Key Value and Alias ... 17
HTTP Header Information... 18
Mediation ... 19
More than One Mediation Partner ... 21
Postclick Tracking Beacon Tags ... 22 In this chapter
2012-12-18 Page 8 of 216
Getting Started in ADTECH Mobile
This topic discusses the process of getting started with ADTECH Mobile. The process consists of the following stages:
No. Stage Description
1 Prepare IQ The CRM prepares the network with respective network features, keygroups, keyword tree, tag templates, banner templates etc. 2 Create
placements The customer creates five mobile placements in ADTECH IQ in five different sizes (see MMA Mobile Banner Sizes on page 14) for each placement on the mobile app. For details see Device Screen Size Categories on page 13 and How to Set Up Placements.
3 Prepare
Website/App The app developer prepares the app for use with ADTECH Mobile. For details see Preparing the App for Mobile Users and ADTECH Mobile SDK on page 24.
4 Choose Me-diation partner
The customer decides whether he wants to work with a mediation partner that fills the remnant inventory. For details see Mediation on page 19 and get in touch with your ADTECH Client Service con-tact person.
5 Book
cam-paign The trafficker books the Mobile campaigns in the ADTECH IQ user interface. 6 Detect
in-formation The Mobile Ad Server detects the device information during the ad request and delivers the banner in the correct size. For details see Mobile Ad Request on page 12 and Keyword, Key Value and Alias on page 15.
Introduction Getting started
2012-12-18 Page 9 of 216
ADTECH Display versus ADTECH Mobile
This topics describes the differences between ADTECH Display and ADTECH Mobile • Mediation: Collaboration with a mediation partner for the monetization of your
remnant inventory is supported.
• Unique devices: Unlike the display advertising industry, mobile advertising has fewer standards and common display formats. Each manufacturer (e.g. Apple) uses its own browser and the devices (e.g. iPhone) have many different screen sizes, resolutions etc. There are many unique devices.
• Device and size detection: ADTECH Mobile allows ads to display properly on all types of devices with the help of device and size detection.
• Tag types: There are new tag types available for ADTECH Mobile. For details see Mobile Tags for Websitesand Code Samples for Apps.
• Webmaster and app developer: In addition to working with the ADTECH IQ user interface, the webmasters and app developers need to prepare the websites and apps for mobile ad serving. For details see Information for Webmasters and Infor-mation for App Developers.
• Manufacturer, device, size, carrier and OS: The ADTECH features keyword target-ing, key value targeting and placement alias are used to pass certain mobile infor-mation in the request URL. For details see Keyword, Key Value and Alias on page 15 and Request URLs with Keyword, Key Value and Alias on page 17.
• Reports: In general, any report can be generated when using ADTECH Mobile (e.g. Keyword reports which contain the devices for mobile targeting). In addition, there is a special mobile report called Invoice Check Mobile.
• ADTECH Mobile Ad Server: The ADTECH Mobile Ad Server receives all mobile ad requests and forwards them to the ADTECH Ad Server.
• Tracking: Postclick Tracking is supported. For details see Postclick Tracking Beacon Tags on page 22.
• HTTPS: Secure tags are not yet supported in ADTECH Mobile.
• Placement refresh interval: You can define a refresh interval for placements in apps. For Details see How to Set the Behavior of the Mobile SDK in ADTECH Mobile in the User Interface.
Introduction Differences to ADTECH Display
2012-12-18 Page 10 of 216
ADTECH Mobile Feature List
This topic describes which features are supported by the ADTECH Mobile solution. The following features are supported/ not supported by ADTECH Mobile:
Features ADTECH Mobile
ADTECH Analytics Campaign layers
Click or transaction rate based banner optimiza-tion
Companion ad and tiling
Cookies (and cookie related features) Cookie targeting
eCPM
Forwarding Traffic Frequency Capping
Impression and click based delivery IMS forecast
IP based country targeting via key values IP based geo targeting
Key Values
Keywords (additional) Live Monitor
Live Log Live Test*
Interface to Mediation partners: • InMobi • Inneractive • Mojiva • Nexage • Smaato • Millennial
Mobile keyword tree in Forecast campaign Multiple placements on one page
Online Targeting Tab Postclick Tracking
Reporting and Report Wizard Re-Targeting
Introduction
Features of ADTECH Mobile
2012-12-18 Page 11 of 216
Features ADTECH Mobile
Server side cookies Server-to-server pixel Size detection Targeting by carrier
Targeting by device and manufacturer Targeting by OS
*not for custom domains
The following features are supported/ not supported by ADTECH Mobile for Mobile Web and Mobile App:
Features Mobile
Web Mobile App Special banner formats/templates (e.g.
full-screen or expandable banner)
Rich media support (e.g. ADTECH Canvas) Image banner formats
Other banner formats: • Animated images • HTML, HTML 5 • JavaScript • Flash • Video
SDK support for platforms:
• iOS
• Android
Key value for app name
Key value for Mobile SDK version Placement refresh interval Third party SDK support ADTECH Mobile
feature comparison for Mobile Web and Mobile App
2012-12-18 Page 12 of 216
Mobile Ad Request
No. Stages Description
1 Ad request The mobile device requests a mobile web page and makes an ad request to the Mobile Ad Server.
2 Device detection The Mobile Ad Server detects screen size, device, carrier and manufacturer information and adds these values to the ad request. For details see Request URLs with Keyword, Key Val-ue and Alias on page 17 Keyword on page 15.
3 Ad request The Mobile Ad Server forwards the ad request to the ADTECH Ad Server including the values from the device detection. 4 Campaign
selec-tion The ADTECH Ad Server checks whether a campaign is availa-ble. 5 Ad response The ad response (campaign or default) is sent to the Mobile
Ad Server. 5a Check for
Media-tion Partner (If mediation is activated and if ADTECH has returned a de-fault) The Ad Server makes an ad request to the mediation net-work(s).
5b Mediation ad
re-sponse (If a mediation partner exists) The network sends the ad response to the Mobile Ad Server. 6 Ad delivery The Mobile Ad Server delivers the ad.
For details on mediation see Mediation on page 19. Mobile ad request
image
2012-12-18 Page 13 of 216
Device Screen Size Categories
This topic describes the device screen size categories. After the size of a device has been detected by the Mobile Ad Server, it is passed to the ADTECH Ad Server via the alias feature (for details see Keyword, Key Value and Alias on page 15). The screen size is put into one of five device screen size categories predefined by the Mobile Market-ing Association (MMA). These categories depend on the width of the device screen and can be compared to t-shirt sizes (S-XXL). The banners are then delivered to the corresponding screen size category. For details see MMA Mobile Banner Sizes on page 14.
The table below shows the device screen size categories with the matching device screen size:
Size categories Screen width Size keys S (small) 0-167 pixel 1 M (medium) 168-215 pixel 2 L (large) 216-299 pixel 3 XL (extra large) 300-319 pixel 4 XXL (extra extra large) 320+ pixel 5 Introduction
2012-12-18 Page 14 of 216
MMA Mobile Web Banner Ad Sizes
The Mobile Marketing Association (MMA) is the premier global association that strives to stimulate the growth of mobile marketing and its associated technologies. The MMA is a global organization with 400 members representing over twenty countries. MMA members include agencies, advertisers, device manufacturers, carriers and op-erators, retailers, software providers and service providers, as well as any company focused on the potential of marketing via mobile devices.
The MMA has defined 5 recommended banner sizes for mobile devices (see Standard mobile banner sizes below) and ADTECH IQ is compliant with them.
• The 5 recommended Mobile Web Banner Ad sizes defined by the MMA are put into the five device screen size categories (see Device Screen Size Categories on page 13).
• They are available in 4:1 and 6:1 aspect ratios.
• ADTECH supports these banner sizes and also a default banner size that will be delivered if the device is unknown.
Note: For details on the MMA guidelines see http://mmaglobal.com/mobileadvertising.pdf. The MMA has defined recommended universal Mobile Web Banner Ad sizes for each size category. If a mobile device has the size category medium for example, then the universal Mobile Web Banner Ad should have the size 168x42.
The table below shows the standard Mobile Web Banner Ad sizes defined by the MMA:
Device size Universal Mobile Web Banners (in pixels wide x tall) (MMA category) 4:1 Aspect Ratio 6:1 Aspect Ratio
small 120x30 120x20 medium 168x42 168x28 large 216x54 216x36 x-large 300x75 300x50 xx-large 320x75 320x50 Notes:
• You need to decide together with the ADTECH client whether you have to use the 6:1 or the 4:1 ratio.
• The actual height and width for each of the banner sizes can vary from those out-lined above depending on the territory. Some countries have their own guidelines, however, the size detection in ADTECH Mobile is based on the MMA guidelines. • There are no MMA banner recommendations for tablets today.
About the MMA
Standard mobile banner sizes
MMA recommended Mobile Web Banner Ad sizes
2012-12-18 Page 15 of 216
Keyword, Key Value and Alias
ADTECH Mobile uses three targeting features (keyword, key value and alias targeting) to pass information to the Ad Server. This topic describes which information is passed using which ADTECH IQ feature. Furthermore, the properties and restrictions of the features are outlined.
The keyword feature is used to pass manufacturer and device information. Example: key=rld-manufacturer_device
Properties and limitations
• Keyword targeting (here: manufacturer and device targeting) is supported by the IMS.
• A maximum of 5,000 keywords can be used in a flight/campaign. • Keywords are limited to 60 characters in ADTECH IQ.
• Individual phone user agent updates will be conducted once/twice a month, so it is possible that a new device may not be recognized until an update occurs.
• In the event that an update for device detection is needed to address a wholesale change on the part of a device manufacturer (such as an OS update that affects a high proportion of phones), it will be completed within a 48 hour time period from notification.
• There is a keyword tree predefined by ADTECH and uploaded into your network for preselecting keywords. For details see The Keyword Tree.
• Upon request, the Mobile Device Targeting keyword tree can be activated for the various campaign types.
The key value feature is used to pass carrier and operating system (OS) information. Example: kvmcarrier=carrier; kvmos=os
Properties and limitations
• If the version of the OS is available, it will also be passed (e.g. kvmos=android:android_1_0).
• Key value targeting (here: carrier and OS targeting) is not supported by the IMS. • ADTECH will predefine a keygroup and upload it into your network for preselecting
key values. For details see The Keygroups.
• All key values that you want to use in a mobile campaign need to be within the same keygroup.
Introduction
Keyword
2012-12-18 Page 16 of 216 The alias feature is used to pass size information. Each mobile placement has an alias that consists of a description, position and size key. The size keys identify the size of the placement. For details see Size keys below.
Example: mobilesportsboxingandandroidbanner-top-1 (ali-as=description-position-size key)
Note: For details on the Alias feature see the separate Alias user guide. Properties and limitations
• The “description”should be as detailed as possible and contain the entire path from website to page to section etc. without hyphen or underscore.
• The “position” must be “top”, “bottom” or “other1” to “other8”. For details see Position below.
• The “size key” must be a number between 1 and 5. For details see Size keys below. • Once the device is identified, the system will dynamically overwrite the size in the
tag with the correct size for the device.
• For details on the allowed characters see the separate Alias user guide. Position
There are currently 10 positions available:
Position Description Usage
top An ad that is positioned on the top of the page. mandatory other1 One of 8 ads that is positioned randomly. optional other2... One of 8 ads that is positioned randomly. optional other8 One of 8 ads that is positioned randomly. optional bottom An ad that is positioned the lower part of the page. optional Notes:
• A position needs to be unique, e.g. there cannot be two placements called “oth-er1”.
• Each of the tags must be wrapped in div containers (<div></div>). Without the div container ads may not show in the correct position.
Size keys and device size category The following sizes are used:
Size key Device Size Category 1 S 2 M 3 L 4 XL 5 XXL Alias
2012-12-18 Page 17 of 216
Request URLs with Keyword, Key Value and Alias
This topic shows example request URL for EU and US that are • passed from the device to the Mobile Ad Server and
• passed from the Mobile Ad Server to the Ad Server and which contain the data from the device, size, carrier and OS detection via keyword, key value and alias in-formation.
http://a.adtech.de/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;grp=[group];random=129906372986
http://a.adtechus.de/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;grp=[group];random=129906372986
http://adserver.adtech.de/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;
key=rld-APPLE_IPHONE;kvmcarrier=VODAFONE_UK;kvmos=android;
alias=mobilesportsboxingandandroidbanner-top-4;grp=[group];
random=129906372986
http://adserver.adtechus.com/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;
key=rld-APPLE_IPHONE;kvmcarrier=VERIZON_US;kvmos=android;
alias=mobilesportsboxingandandroidbanner-top-4;grp=[group];
random=129906372986
The URL contains the following sections:
Functionality Targeting Variable Example Description Keyword
Manufactur-er, Device
key rld-APPLE_IPHONE Apple, iPhone
Key value Carrier/OS kvmcarrier/
kvmos VODAFONE_UK/ VERIZON_US Vodafone UK/ Verizon USA
Alias Size alias
mobilesportsbox- ingandandroidban-ner-top-4
4=XL device screen category
Introduction
Example Request URL EU from device to Mobile Ad Server Example Request URL US from device to Mobile Ad Server Example Request URL EU from Mobile Ad Server to Ad Server
Example Request URL US from Mobile Ad Server to Ad Server
2012-12-18 Page 18 of 216
HTTP Header Information
This topic describes what needs to be done in case the Mobile tag is sent to third party systems and the IP address and user agent cannot be properly passed.
Some publishers and networks are not able to pass neither the IP address nor the user agents of the devices because they send the Mobile Tag to third party systems (e.g. other ad server or SDK) who return the Mobile Tag to ADTECH as third party redirect. In order to receive the IP address and user agent of the device, it is imperative that x-forward-for (XFF) is used to forward the original header information. Both is required to use ADTECH Mobile with all features, such as size detection, carrier detections etc. Introduction
Use case
2012-12-18 Page 19 of 216
Mediation
When using ADTECH Mobile, it is possible to collaborate with a mediation partner. This topic describes what mediation is and how it is used.
You can collaborate with a mediation partner for the monetization of your remnant inventory. In case a default ad would be delivered, an ad request is made to the medi-ation partner who fills the remnant inventory. For details see Mobile Ad Request on page 12.
ADTECH offers an interface to connect the mediation partner with the Mobile Ad Server. For this process, the following points need to be considered:
Point Description
Publisher ID A publisher ID is given by the mobile mediation partner and helps to identify a customer.
Mapping list When setting up a mediation partner, the customer outlines his website structure and targeting criteria. This results in IDs that need to be mapped to the placements in ADTECH IQ. This can either be conducted via the entire or part of the alias description (for details see Keyword, Key Value and Alias on page 15).
Examples:
• Sport_homepage-top-1 (mapping name = Sport) • Sport-homepage_page-top-1 (mapping name = Sport) Notes:
• Sport is the mapping name which is mapped to the mediation part-ner’s ID.
• The mapping name is put at the beginning and an underscore (_) or hyphen (-) is used to separate the mapping name from the rest of the alias. For granular mediation, the mapping name should be as detailed as possible before the first hyphen or underscore. To sepa-rate the website from the page name, you could use a dot instead of a hyphen or underscore.
Example for mediation by page:
m.websitename.com.pagename-bottom-1
Example for mediation by placement:
m.websitename.com.pagename.position-bottom-1
Do not use:
m.websitename.com_news_business_news_mobileweb-bot tom-1
In case network mediation is used, it is possible to pass key values. However, they need to have fixed formats. For details please reach out to your ADTECH Client Service contact person.
Introduction
What is mediation?
Publisher ID and mapping list
Mediation and key values
2012-12-18 Page 20 of 216 In case network mediation is used and fullscreen ads are to be mediated through the Mediation partner’s network, the following points have to be considered:
• There is currently no mechanism to signal the mediation partner to return an ad matching the exact size (height and width) of the device.
• The publisher needs to communicate with the mediation partner how the place-ments should be passed.
• If the mediation partner does not support mediation of fullscreen ads, the publish-er must remove the placement from the mediation mapping list so that it will not be sent to the mediation partner.
Mediation and fullscreen banners
2012-12-18 Page 21 of 216
More than One Mediation Partner
When working with more than one mediation partner, there are currently two possi-ble scenarios for the set-up:
• by priority • by weight
The two scenarios are described below.
The configured mediation partners will be called in a specific order. Example:
• Smaato - Priority 1 • InMobi - Priorty 2 • Mojiva - Priority 3
In this case, we would always try to call Smaato first. In case Smaato would not return an ad, we continued and called InMobi. If InMobi returned no ad either, we would continue and call Mojiva. If none of the partners returned an ad, an ADTECH default banner would be delivered.
The configured mediation partners will we called according to probabilities.
• You assign probabilities to the different mediation partners according to which they will be selected.
• A mediation partner is randomly selected and an ad is requested. If the partner does not return an ad, ADTECH subtracts its probability value from 100 and re-peats the above step with the remaining probability.
Example:
• Smaato - 80% probability • InMobi - 5% probability • Mojiva - 15% probability
In this example, Smaato is more likely to be called first than InMobi and Mojiva. Like-wise, Mojiva is more likely to be called than InMobi.
Introduction
Priority order set-up
2012-12-18 Page 22 of 216
Postclick Tracking Beacon Tags
It is possible to use the postclick tracking feature in ADTECH Mobile. However, you need special postclick tracking beacon tags with a different host name
(a.adtech.de/ instead of adserver.adtech.de etc.). This topic shows example postclick tracking beacon tags for ADTECH Mobile. For details see the separate Post-click Tracking documentation.
Note: It is possible to have different postclick tracking beacon tag templates (e.g. for Display and for Mobile) in your network.
Below you find example beacon tags (user tracking and postclick tracking tags) for ADTECH Mobile.
Example User Tracking Beacon Tag US
<!-- Postclick Tracking Tag Start --> <script type="text/javascript"
src="http://a.adtechus.com/utrack/3.0/25/0/0/0/BeaconId=-2;rettype=img;subnid=1;Section=[Ple ase insert Section here]"></script>
<noscript> <img
src="http://core.adtechus.com/utrack/3.0/25/0/0/0/BeaconId=-2;rettype=img;subnid=1;Section=[ Please insert Section here];random=[Random 10 char token]" />
</noscript>
<!-- Postclick Tracking Tag End -->
Example User Tracking Beacon Tag EU
<!-- Postclick Tracking Tag Start --> <script type="text/javascript"
src="http://a.adtech.de/utrack/3.0/25/0/0/0/BeaconId=-1;rettype=img;subnid=1;Section=[Please insert Section here]"></script>
<noscript> <img
src="http://core.adtech.de/utrack/3.0/25/0/0/0/BeaconId=-1;rettype=img;subnid=1;Section=[Ple ase insert Section here];random=[Random 10 char token]" />
</noscript>
<!-- Postclick Tracking Tag End -->
Introduction
Mobile beacon tag examples for US and EU
2012-12-18 Page 23 of 216 Example Sales Beacon Tag US
<!-- Postclick Tracking Tag Start --> <script type="text/javascript" src="http://a.adtechus.com/pcsale/3.0/25/0/0/0/BeaconId=-1;rettype=img;subnid=1;SalesValue=[ AmountInCent];custom1=[article]"></script> <noscript> <img src="http://core.adtechus.com/pcsale/3.0/25/0/0/0/BeaconId=-1;rettype=img;subnid=1;SalesValu e=[AmountInCent];custom1=[article];random=[Random 10 char token]" />
</noscript>
<!-- Postclick Tracking Tag End -->
Example Sales Beacon Tag EU
<!-- Postclick Tracking Tag Start --> <script type="text/javascript" src="http://a.adtech.de/pcsale/3.0/25/0/0/0/BeaconId=7200;rettype=img;subnid=1;SalesValue=[A mountInCent];custom1=[auto]"></script> <noscript> <img src="http://core.adtech.de/pcsale/3.0/25/0/0/0/BeaconId=7200;rettype=img;subnid=1;SalesValue =[AmountInCent];custom1=[auto];random=[Random 10 char token]" />
</noscript>
2012-12-18 Page 24 of 216
Chapter 2
ADTECH Mobile SDK
This chapter describes the ADTECH Mobile SDK for app developers.
Topic Page
General Information About the ADTECH Mobile SDK ... 25 ADTECH Mobile SDK: iOS ... 52 ADTECH Mobile SDK: Android ... 113 ADTECH Mobile SDK: Windows Phone ... 157 ADTECH Mobile SDK: Windows 8 ... 180 ADTECH Mobile SDK Limitations ... 205 Introduction
2012-12-18 Page 25 of 216
2.1
General Information About the ADTECH Mobile SDK
Topic Page
ADTECH Mobile SDK Release Notes ... 26 Purpose and Contents of the ADTECH Mobile SDK ... 27 Responsibilities of the App Developer ... 28 Compliance with Advertising Standards ... 29 MRAID Compliance ... 30 ORMMA Compliance ... 32 VAST Compliance ... 33 The ADTECH Mobile SDK Features and Properties ... 34 ADTECH Mobile SDK Feature Matrix for Different Platforms ... 36 Placement Configuration for the ADTECH Mobile SDK ... 38 Tracking Unique Devices with the Mobile SDK ... 44 Logging the ADTECH Mobile SDK Activity in the Console ... 45 Caching and Offline Display ... 46 Video Ads in the ADTECH Mobile SDK ... 48 Mediation in the ADTECH Mobile SDK ... 51 In this chapter
2012-12-18 Page 26 of 216
ADTECH Mobile SDK Release Notes
See the different release note for the several platforms: • iOS: ADTECH Mobile SDK Release Notes (iOS) on page 61
• Android: ADTECH Mobile SDK Release Notes and API Changelog (Android) on page 119
• Windows 8: ADTECH Mobile SDK Release Notes (Windows 8) on page 185 Platform specific
2012-12-18 Page 27 of 216
Purpose and Contents of the ADTECH Mobile SDK
This topic describes the difference between mobile for website and mobile for apps as well as the purpose of the SDK and the required contents.
Mobile users open mobile websites and apps. As the display of banners is different in mobile websites than in mobile apps, the two need to be treated separately. The ADTECH Mobile user guide concentrates on Mobile in general and Mobile for websites whereas the ADTECH Mobile for App Developers user guide concentrates on the tech-nical information for app developers (SDK). As the app developer does not have access to the user interface of ADTECH IQ, the trafficker needs to book standard mobile campaigns for websites in addition to mobile campaigns for apps. Therefore, the pro-cedures and structures regarding apps are found in the ADTECH Mobile Websites guide and not in the ADTECH Mobile for App Developers guide.
The main purpose of the SDK is to help the application developer with placing ads inside their developed application. The SDK is intended to have a simple, consistent and user friendly interface that helps developers integrating seamlessly banners and interstitial ads into their application’s banners, interstitial ads and ads inside video players.
Important: We cannot guarantee that applications built with HTML-to-app frame-works (like PhoneGap, Titanium etc.) will work with the ADTECH Mobile SDK, therefore we cannot offer any support for them.
The SDK is delivered as a .zip package. It contains:
• The binaries and the resources: The SDK library together with the header files and some additional configuration files (jar for Android and framework for iOS). • Documentation: The SDK interface documentation.
• Sample application: A sample app that works out of the box, where the SDK is in-cluded and used in a simple way.
• Readme.txt: Text file containing SDK install and setup instructions.
• License.txt: Text file containing the license statements for the SDK and the third party libraries used.
Important: Software that uses the ADTECH Mobile SDK should provide proper attribu-tion for the 3rd party libraries used by the SDK. You can find these libraries and their license statements in the License.txt file.
Introduction Mobile on websites versus mobile on apps Purpose Contents
2012-12-18 Page 28 of 216
Responsibilities of the App Developer
The developer who uses the ADTECH Mobile SDK is responsible for the following tasks: • Integrating the ADTECH Mobile SDK into the application.
• Ensuring that placements have been created. • Testing the successful ad delivery.
Most of the provided code snippets in the following documentation must be modified in order to work with your network’s setup. The values provided in the code examples are not meant to be copied 1:1 and have to be coordinated with your trafficker. This applies to all values provided in the ad-configuration, e.g. Network-ID, Subnetwork-ID, Domain, placement alias etc.
For the values that apply to your application, please talk to your ad ops team. Tasks of the ADTECH
Mobile SDK developer
2012-12-18 Page 29 of 216
Compliance with Advertising Standards
Platform Compliance with Standards
iOS MRAID 1.0, MRAID 2.0, ORMMA Level 2, VAST 2.0 Android MRAID 1.0, MRAID 2.0, ORMMA Level 2, VAST 2.0 Windows Phone MRAID 1.0
Windows 8 MRAID 1.0
Note: For platform limitations and differences from the standard specifications see ADTECH Mobile SDK Limitations on page 205.
2012-12-18 Page 30 of 216
MRAID Compliance
The ADTECH Mobile SDK is compliant with the IAB standards and guidelines.
MRAIDhttp://www.iab.net/mraid, or “Mobile Rich Me-dia Ad Interface Definitions” is the IAB
http://www.iab.net/ Mobile Marketing Center of Excel-lence’s project to define a common API for mobile rich media ads that will run in mo-bile apps. This is a standardized set of commands, designed to work with HTML5 and JavaScript, that developers creating rich media ads will use to communicate what those ads do (expand, resize, get access to device functionalities such as the accel-erometer, etc.) with the applications they are being served into.
There are no requirements in this specification for the native app developers. They should follow the instructions and interface provided by the ADTECH Mobile SDK for integrating ads into the application.
There are two versions of MRAID that have been published:
• MRAID 1.0: This is latest official version that has been published on the 20th of Oc-tober, 2011.
• MRAID 2.0: It has been published at the same time as MRAID 1.0, adding features that allow ad designers to make use of device hardware capabilities. The MRAID 2.0 specification is not yet final, it is only in draft state, but it is very likely for it not to change much by the final release date.
The methods and events identified in this version of MRAID provide a minimum level of requirements for rich media ads, primarily to display HTML ads that can change size in a fixed container.
Although MRAID 1.0 addresses a minimum level of functionality, the standards of MRAID remain high. In this and particularly in future versions of the API, the IAB fo-cuses on
• High interoperability: ads developed to run in one MRAID container can run on MRAID containers of multiple platforms and operating systems.
• Graceful degradation: ads developed to take advantage of all the MRAID features also have the capacity to downgrade gracefully as needed. This will be especially important as gaining access to device functionalities becomes part of MRAID’s scope in the future.
• Progressive complexity: ad design using the API should be simple, adding complex-ity only as necessary.
The ADTECH Mobile SDK is MRAID 1.0 compliant. This means that it can display and interact with ads that conform to the MRAID 1.0 specifications. There is one difference from the MRAID 1.0 specification in the iOS implementation, in that sizes are reported to the ad in device independent pixels, i.e. iOS points. For platform specific limitations see ADTECH Mobile SDK Limitations on page 205.
Mobile SDK MRAID Compliance
2012-12-18 Page 31 of 216 MRAID 2.0 gives ad developers access to the hardware device capabilities, such as: playing video and audio, location, heading, orientation, tilt, shake events, camera, phone, calendar, email and sms. It allows better control over how users interact with ads, by providing properties for events like expansion and resizing. MRAID 2.0 greatly improves the way the ad communicates with and uses the device it is displayed on. The ADTECH Mobile SDK is MRAID 2.0 compliant except it does not implement support for the request/response method/event pair. For other platform specific limitations see Platform Specific Mobile SDK Limitations on page 206.
2012-12-18 Page 32 of 216
ORMMA Compliance
ORMMA is an industry wide initiative for advertisers to have one common set of rules for displaying rich media ads across platforms. Ad designers that have one API to use when creating ads know that their ad will display on all ORMMA-compliant apps and sites.
The ORMMA standard is split into three levels to simplify understanding and adoption. • Level 1: expand and collapse
• Level 2: access native features • Level 3: cache content
2012-12-18 Page 33 of 216
VAST Compliance
This topic describes on high level what VAST is and how the ADTECH Mobile SDK is related to it.
VAST, or “Digital Video Ad Serving Template”, is the IAB specification for a universal XML schema for serving ads to digital video players, and describes expected video player behavior when executing VAST – formatted ad responses. VAST provides a common protocol that enables ad servers to use a single ad response format across multiple publishers/video players.
There are three versions of VAST that have been published: Version Description
VAST 1.0 In 2008, the IAB introduced the first version of VAST to the video advertising marketplace, which has since been widely adopted throughout the industry. VAST 2.0 In 2009 features were added that enabled additional functionality and more
clarity.
VAST 3.0 It was released as a draft in April 2012 and was open for feedback until May 10, 2012. It has not yet been released as the final version up until the date of writ-ing.
The ADTECH Mobile SDK provides support for a subset of the VAST 2.0 specification, namely it supports linear video and non-linear ads. There is no support, yet, for com-panion ads and an analysis will have to be performed as to assess their relevancy in a mobile application environment, due to their web-page oriented nature.
Introduction
What is VAST?
How the ADTECH Mobile SDK supports VAST
2012-12-18 Page 34 of 216
The ADTECH Mobile SDK Features and Properties
Category Properties
OS support • Android versions 2.1 (update 1, API level 7) and higher are support-ed.
• For the iOS SDK versions 2.2.1 and below, iOS 3.1 to iOS 5.1.1 are supported for the banner and interstitial ads. iOS versions 4.0 to 5.1.1 are needed for using the VAST compliant movie player. • For the iOS SDK versions 2.2.3 and above, iOS 4.3 and higher are
supported for all the ads types. Device support • Android: Phone and tablet.
• iOS:
• All devices running iPhone OS 3.1 or higher (iPod, iPhone and iPad) for banners and interstitials. All devices running iOS 4.0 or higher for VAST.
• Starting release 2.2.3 of the iOS SDK, devices using the armv6 CPU architecture are not supported anymore. 2.2.3 brings sup-port for devices using the armv7s architecture (iPhone 5). Placements • The class that implements a placement (ATBannerView), extends
the generic view class of each platform (RelativeLayout on An-droid and UIView on iOS) and will be referred as an ad container. • Ad containers can be placed anywhere on the screen, not only on
the top or bottom.
• Most common ad container size is 320x50 pixels but the developer can set any size as needed.
Ad refresh • The ad refresh is triggered by the placement refresh interval. The developer can set a default refresh interval per placement. • If the ad specifies its own refresh interval than this takes priority
over the one defined by the developer.
• The refresh interval can be 0 or a value between 5 and 3600 that represents seconds.
• 0 means that the ad should never refresh.
• Trying to set a value outside [5,3600] the SDK will reset it to either 5 or 3600.
Animations • When 2 ads switch each other in an ad container, usually the transi-tion is animated.
• The default switch animation can be set by the developer but if the ad specifies its own animation than this takes priority over it. • The animations known to the SDK are:
• slide left • slide right • slide top down • flip right • flip left • none Features and
2012-12-18 Page 35 of 216 Category Properties
Fail / Retry • If a request fails, the SDK keeps retrying another 2 times. • If both of them fail, so that there are a total of 3 consecutive
fail-ures, the SDK stops fetching ads until the user calls the load meth-od again on the ad banner or interstitial.
• While internet connectivity is down, new ads will not be requested. When internet connectivity returns, the SDK will begin fetching new ads on its own.
Interstitial • Interstitial ads usually cover the full application user interface, but the developer can set a custom size if needed.
• Interstitials are short-lived full screen ad containers that can be placed in different moments in an application (e.g. on app startup, when switching between 2 screens in the app).
• Interstitials present one ad and after that they expire or are closed by the user, there is no refresh mechanism.
Mediation • If configured, the SDK can serve ads from other ad providers using their own SDKs internally.
Ad-enabled video player
• Using the VAST compliant video player provided by SDK the app de-veloper can show video content (local or remote, progressive or streamed) and fetches and displays ad during playback as config-ured.
• The movie player component provided by the SDK is very similar, almost identical, to the platform provided one so that it is intuitive and familiar to use.
The SDK uses a container for showing an ad of web-view type, which is implementa-tion specific on each platform (WebView on Android and UIVebWiew on iOS) and be-cause of this the restrictions on what can be displayed is dictated by the base contain-er.
There are no restrictions regarding the types of ads that can be shown. Simple image, animated gif or rich media ads will work, given the constraint of the platform specific web-view. For the video ads the restriction is that they need to have a format sup-ported by the platform.
2012-12-18 Page 36 of 216
ADTECH Mobile SDK Feature Matrix for Different Platforms
Feature iOS Android Windows
Phone 7.5 Windows 8 Display of static image ads (jpg, png, gif,
animated gif)
Display of MRAID 1.0 rich ads VAST linear- & non linear video ads Track mobile video events
Track & report impressions, clicks, views, post-clicks
Track & report rich ad events Banner rotation (refresh interval) Custom animation style on placement level
Fullscreen interstitial
Mediation of static image ads Support for custom key/value Unique user identification (cross app) Tiling & companion ad
Click2call, click2sms, click2mail, click2cal sync (iOS)
Carrier name detection Display of MRAID 2.0 rich ads Track MRAID 2.0 events Report MRAID 2.0 events ORMMA Level 1 & 2
Feature iOS Android Windows
Phone 7.5 Windows 8 Caching of ADTECH static image ads
Caching of ADTECH rich ads Caching of 3rd party MRAID ads Cache disengageable on placement lev-el
Caching of fullscreen interstitials Track offline impressions, views, clicks Report offline impressions, views, clicks Ad display features
Offline delivery features
2012-12-18 Page 37 of 216
SDK iOS Android Windows
Phone 7.5 Windows 8 AdMob iAd Millenial Media Greystripe Vdopia Mediation to 3rd party SDKs
2012-12-18 Page 38 of 216
Placement Configuration for the ADTECH Mobile SDK
This topic shows the configuration that has to be provided for each placement.
The following values can be provided by the user of the ADTECH SDK to configure both the banner ads and the video ones:
• application name • domain
• network ID • subnetwork ID • alias
• additional user defined key value pairs
Additionally, for the banner (and interstitial) ads the user can specify values for these settings:
• animation type • ad refresh interval • group ID
• allow location services
For the video ads the user can specify the following:
• type of linear ads to be served (pre-roll, mid-roll and/or post-roll) • overlays (non-linears) to be shown during content playback • videoDimension
• videoLength • videoBitrate
• maxWrapperRedirections
Some of the above enumerated values have to be provided via static configuration files given the restrictions and best-practices of the respective platforms. These values will be used as defaults in any newly initialized ATBannerView’s configuration. These can then be changed at any time during runtime. This will ensure that all placements are initialized consistently with a minimal of written code, but then if needed they can be configured to suite the application needs.
Configuration that needs to be specified in the configuration file is: • application name • network ID • subnetwork ID • domain • animation type • ad refresh interval • allow location services Introduction
Placement configuration
2012-12-18 Page 39 of 216 Additional values that the user can configure at runtime are:
• domainForVideo (domain for the video ads if it is different from the one used for banners and interstitials)
• alias (the placement description of the ad, mandatory for all kind of ads) • group ID (for companion and tilling)
• additional user defined key-value pairs
• type of linear ads to be served (pre-roll, mid-roll and/or post-roll) • overlays to be shown during content playback
• videoDimension • videoLength • videoBitrate
• maxWrapperRedirections
Mediation can be set up via the configuration file. For each mediation partner there should be an additional entry. See platform specific mediation chapter for learn more details (How to Use Mediation for Third Party Advertisement SDKs in Android on page 146 and How to Use Mediation for Third Party Advertisement SDKs in iOS on page 105).
Value Description
Application name The application name will be used by the ADTECH IQ server for tracking purpose and statistics. The application name needs to be the same for all placements in an app and for this reason it can only be specified via the configuration file. Changing it at runtime is not possible.
Network and
subnetwork IDs These values identify a user and campaign on the ADTECH IQ server and can be configured per placement level. By default each placement will have the same values configured (provided via the configuration file) meaning that all the placements will show ads coming from the same ADTECH IQ user and campaign. However, at runtime these values can be changed as needed and this way the developer can configure two or more placements that will show ads from different campaigns or even more from different ADTECH IQ users.
Domain and
do-mainForVideo Just like the network and subnetwork ID, the domain is also configurable at runtime and per placement level. These will allow the developer to have in the same application placements that present ads coming from different domains.
The video ads can have their own domain specified in the configuration file for cases when it is different than the one used for serving banner and interstitial ads. It can also be changed at runtime on a per video in-stance basis.
2012-12-18 Page 40 of 216 Value Description
Alias The alias is set per placement and its purpose is to uniquely identify each placement within one app. For this reason the same alias should not be shared by multiple placements. The developer must ensure that the alias used for a placement exists on the ADTECH IQ server.
The alias currently conforms to one of the following patterns on the ADTECH IQ server:
• mappingname-position-size
• mappingname_description-position-size
• mappingname|description|website-position-size
where size is a numeric value in the range 1 to 5. As ADTECH deals with various customer requirements the format of the alias may be required to change, so for this reason the alias is not validated by the SDK
(out-side of checking that it is not Null or an empty string, i.e. "").
Animation type The animation type can be configured per placement level and its pur-pose is to add a visual transition effect for 2 ads changing in one place-ment. In case there is an animation set up in the ADTECH IQ server, the ad will come with its own animation and it will overrule this one set up by the developer at placement level. The possible values that can be used are:
• TOP_TO_BOTTOM: the new ad will transition by pushing the old
one out of the way vertically from a top down direction
• LEFT_TO_RIGHT: the new ad will transition by pushing the old one
out of the way horizontally from left to right
• RIGHT_TO_LEFT: the new ad will transition by pushing the old one
out of the way horizontally from right to left
• FLIP_FROM_RIGHT: the new ad will become visible by flipping the
old one out of the way, right flip
• FLIP_FROM_LEFT: the new ad will become visible by flipping the old
one out of the way, left flip
• NONE: no animation when changing ads
The animation duration is set internally by the SDK to 0.7 seconds. Refresh interval The refresh interval can be set per placement level and its purpose is to
define the time that an ad is shown before a new one replaces it. In case there is a refresh interval set up in ADTECH IQ, the ad will come with its own refresh interval and it will overrule this one set up by the developer at placement level.
The refresh interval can take values between 5 and 3600 seconds. An exception from this rule is a value of 0, it means never refresh. The SDK will internally validate and enforce this restriction on the re-fresh interval:
• If a value is smaller then 5, it will be automatically be set to 5 by the SDK (exception is value 0, in case of which the refresh will be switched off).
• If a value is higher than 3600, it will be automatically set to 3600 by the SDK.
2012-12-18 Page 41 of 216 Value Description
AllowLocation-Services setting This setting is used to allow or disallow the ADTECH Mobile SDK using the Location Services (iOS feature only). The app developer must explic-itly give his consent for the SDK to use the device’s location, either through this setting in the configuration file, or through the configura-tion object of each ad banner or interstitial. By default the value is NO, which means the SDK will not use the user’s location for advertising purposes.
Important: 3rd party SDKs that are used by the mediation feature are not affected by this setting. They might or might not have a specific way to allow or disallow usage of the location services for their purposes. Group ID The group ID is set per placement level and its purpose is to identify
placements that need to show ads in companion and tilling setups. By setting the same group ID value for two or more placements will ensure that the placements will show either companion ads or tiling ads. This is resolved at ADTECH IQ server level and the only responsibility of the SDK user is to correctly set the group ID values for the placements.
By default, each placement has the group ID set to 0 and this signals to the server that this is a standalone placement. The value of the group ID does not matter as long as it is the same for different placements. E.g. if you have 2 placements on one screen that you want to show tilled ads, it does not matter that you set the group ID to 100 or 200, as long as it is the same for both placements.
User defined key
value pairs Beside the predefined ad configuration properties the user can add ad-ditional key value pairs for a given placement. These key value pairs will be sent to the server when the ad request is made. The responsibility of the developer is to ensure these keys are defined on the ADTECH IQ server and the correct key values are used in the placement configura-tion.
A possible situation when additional key values might be used is when the developer wants to deliver more targeted ads.
Example: If the developer knows the app user’s gender and age, they could specify the gender and age of the app user to the placement so that the ADTECH IQ server can deliver the male or female targeted ads while also taking in consideration their age.
2012-12-18 Page 42 of 216 Value Description
Linear video ad
types to be served The configuration for a video player instance allows specifying the type of video ads to be served. There are three types of linear ads: • Pre-roll ads: they are presented before the video content gets to
play and be displayed
• Mid-roll ads: they are presented at some point during the playback of the video content. The content is paused, the mid-roll ads are played and then the content resumes playback.
• The time of showing the mid-roll can be configured server side using the web interface.
• If not configured server-side, the middle of the video content is chosen as the presentation time.
• If the media being played back is stream based (might have an undetermined length) and the time for showing the mid-roll is not specified server-side, then the mid-roll ad will not be pre-sented as no appropriate time for showing it can be determined. • Post-roll ads: they are presented at the end the video content being
played back
Any combination of these types can be set on the video player instance configuration.
Overlays to be shown during video content playback
The configuration of a video player instance allows specifying how many overlays (non-linear ads) to show during content playback.
Only image overlays are supported at the current time (StaticResource with an image mime-type in VAST terminology).
For each overlay you can configure the following:
• startTime: the time interval of content playback, specified in
sec-onds, after which to start displaying the overlay
• duration: the time interval of content playback, specified in
sec-onds, to keep displaying the overlay for.
• placement: Position inside the video area to place the overlay at.
Possible values are: bottom, top, left and right.
• percentOfMargin: The value of margin to leave between the edge of
the screen and the overlay specified in percents. E.g. With a bottom placement and percentOfMargin of 10, the overlay will be placed at 10% of the video height from the bottom edge.
• secondsUntilDismissable: Specifies the number of seconds to wait
until allowing the user to dismiss the overlay by the close button on the top right corner. Beside the positive values meaning actual sec-onds to wait there are some special values:
• Default: The time to wait is determined by the SDK, currently as
half of the duration
• NotAllowed: Dismiss is not allowed on the overlay and the close
button is not shown
• AllowedFromBeginning: Dismiss is allowed from the moment
the overlay is shown
Any number of overlays can be configured to be shown on the video player, even with overlapping intervals.
2012-12-18 Page 43 of 216 Value Description
The video
dimen-sion This is an optional value for filtering video ads to be returned by the server. The dimension is specified as a width and height pair of values and if set, the server will return only video ads of the specified size. The video length This optional value is used to limit the maximum length of the video ads
being served. The values is specified in seconds and, if set, only video ads of that length or shorter will be served.
The video bitrate This optional value is used to serve only video ads of the specified bi-trate. The value is measured in kbps and, if set, only video ads of the same bitrate will be served.
If not specified and there are multiple video ad alternatives to be shown with different bitrates, the SDK will chose one based on the detected Internet connectivity type:
• if Wifi is available: the ad with the highest bitrate is chosen • if Wifi is not available: the ad with the lowest bitrate is chosen The max wrapper
redirections This is an advanced optional setting that allows the app developer to configure how many redirections, in the way defined by the VAST speci-fication, to follow until the SDK gives up obtaining the video ads. The default value is 3.
2012-12-18 Page 44 of 216
Tracking Unique Devices with the Mobile SDK
This topic describes how ADTECH uniquely identifies devices within mobile apps. Many ADTECH Ad Server features, such as Frequency Capping and Re-Targeting are based on unique device identification. This topic specifies which information will be passed to the ADTECH Ad Server.
Each mobile device has its own, fixed identification property and this identifies a de-vice cross-application. For Android the UDID of the dede-vice.
For iOS before 6.0 or ADTECH Mobile SDK versions before 3.0, a unique string is gen-erated the first time the application is used and is passed to the ADTECH Ad Server when the ad request call is performed. This is identified by the appguid key in the re-quest URL. (E.g. appguid=faf5341a39919352a4f9bde4d6de5396). Each applica-tion creates its own identifier.
Starting iOS 6.0 and ADTECH Mobile SDK version 3.0, the OS provided advertisin-gIdentifier is used (see here). This value is shared among applications and is changed only when the device is erased. If the user limits ad tracking in the device settings, this identifier is not used anymore.
Identifying unique devices Unique device ID in Android Unique device ID in iOS
2012-12-18 Page 45 of 216
Logging the ADTECH Mobile SDK Activity in the Console
By default the SDK is provided with logging turned off, but the developer can enable logging of different levels. This will ensure that all relevant SDK activity information is logged to the console at runtime.
For details see the Android or iOS topics for a list of available logging levels: • How to Set the SDK Log Level (Android) on page 139
• How to Set the SDK Log Level (iOS) on page 76 About logging
2012-12-18 Page 46 of 216
Caching and Offline Display
Caching refers to the capability of the ADTECH Mobile SDK to fetch and store ads and ad related assets in advance. The purpose of this is to improve the overall user expe-rience by having the ad assets already downloaded and ready when the time comes to show the ad while online or to be able to show ads while the mobile device is not connected to the internet.
Performance is obtained by having an ad ready when a new one is needed and having its resources locally available. When it is time to show a new ad, all the needed data for it is available without having to perform networking operations. This can lead to dramatic performance improvements.
By default caching is enabled in the ADTECH Mobile SDK. Caching can be disabled only server side on a placement level. The application developer does not have direct ac-cess and can not intervene with the cache used by the ADTECH Mobile SDK.
The ADTECH Mobile SDK will hold individual caches for unique configurations. This means that if each placement has a unique configuration then each placement will have its own cache, but if some placements share the same configuration values than there will be one cache that will serve the placements. The following configurations identify an individual cache: domain, network ID, subnetwork ID, alias.
The advertiser can create ads suitable for offline display and the ADTECH Mobile SDK is able the cache those ads in advance and play them even of the mobile device is not connected to the internet.
The ADTECH Mobile SDK will track and record ad events that occur while the device is offline and will bulk report these events when the device goes online again.
For performance reasons the ADTECH Mobile SDK will skip from caching video and audio components of the ad even if these assets are part of the cache manifest that the ad is delivered with. Because of this, when offline, even if the ad is offline enabled, the video and audio is not available in it.
The ADTECH Mobile SDK will only cache ADTECH ads that are specially marked as cacheable. Any 3rd party mediated ads are not cached.
The first time an ad is requested the caching will try getting more ads and cache their resources. This can have small networking performance degradation on the applica-tion using the SDK. In order to reduce this effect, only one networking connecapplica-tion is used at one time (per cache). The same effect can happen when there are cached of-fline events that need to be reported when Internet connectivity is available.
The resources for cached ads are downloaded to the Library/Caches folder from the application space. Depending on how many ads are cached and how many caches are there, these resources will take up some available storage space. Cleanup of lefto-ver/unused resources is performed at each application startup (when the first banner view or interstitial is created). Normally, each ad gets its resources deleted after dis-play is done for them, but because of unexpected application terminations, leftover resources can remain stored until the next application run.
Purpose
Configuration
Offline display / offline event tracking & reporting
2012-12-18 Page 47 of 216 If caching the resources of an ad fails (maybe due to changing networking conditions), the ad is marked as non-cacheable and will be displayed online only, but the success-fully stored resources for it will be served from local storage, speeding up display. Cacheable ads usually contain an expiration date that specifies how long an ad should be stored for delivery on the device. If this is not the case, the ADTECH Mobile SDK will automatically attach an expiration date 7 days in the future to it. Cacheable ads will be removed from the cache, as soon as the SDK detects that they have expired. This will be checked on each application startup. Delivered ads will be removed from the cache, no matter the expiration date.
Offline delivery is limited delivery. Any feature that requires a loopback to the ADTECH adserver is not going to work while the device is offline, such as Frequency Capping or Tiling and Companion Ads. Offline delivery has the potential risk of counting differ-ences, if a device stays offline for a longer period of time. The moment the ad was requested by the SDK, it is counted as delivered in the ADTECH adserver, even if it was not displayed to the user. Suppose the user deletes the application or will not use it for a longer period of time than the expiration date is, this ad will never be viewed. Any requests to external resources, such as landing pages, are not available when the device is offline at the current release of the ADTECH Mobile SDK. The intent to open those external resources will be reported to the adserver when the device is online again.
2012-12-18 Page 48 of 216
Video Ads in the ADTECH Mobile SDK
This topic details the way to use the provided video player component in a platform independent manner. It also provides some insight into the behavior you can expect when using the player and the way video ads are being tracked and can be engaged with. The in-place limitations related to the VAST specification are stated at the end of the section.
Showing ad-enabled video content is a matter of creating an instance of the provided video player component, configuring it with the campaign details and the type of ads to serve and putting its view on the application interface. The app developer does not need to (nor can it) play the ads manually, it is all done internally by the player. The player determines the appropriate times to fetch and show the ads based on the con-figuration made available to it.
A typical use case for using video player would follow these steps: Step Action
1 Create a new instance of the provided player.
2 Configure it to match an already set up campaign on the ADTECH IQ server.
