User Guide ADTECH Mobile for App Developers ADTECH GmbH 2012-12-18
Table of Contents About this Document... 6 Chapter 1 Framework and Technology 7 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 Chapter 2 ADTECH Mobile SDK 24 2.1 General Information About the ADTECH Mobile SDK... 25 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 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 How to Add a Banner Using Interface Builder (ios)... 64 2012-12-18 Page 2 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 How to Enable/Disable Image Banner Resize... 134 2012-12-18 Page 3 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 How to Add Additional Key-value Parameters to the Ad Configuration (Windows 8)... 197 2012-12-18 Page 4 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 5 of 216
About this Document 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. Copyright and confidentiality All information from the ADTECH user guides is proprietary and to be treated as strictly confidential. Data is exclusively destined for the exclusive and internal use of the ADTECH customer. Any use, transmission, provision of access to third parties, circulation or any other utilization of the data or of information provided, other than contractual, is strictly prohibited. Address and contact ADTECH GmbH Robert-Bosch-Str. 32 D-63303 Dreieich GERMANY Phone: +49 6103 5715-0 Fax: +49 6103 5715-111 E-Mail: info@adtech.de URL: http://www.adtech.de/ 2012-12-18 Page 6 of 216
Chapter 1 In this chapter 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 2012-12-18 Page 7 of 216
Getting Started in ADTECH Mobile Introduction This topic discusses the process of getting started with ADTECH Mobile. Getting started 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 3 Prepare Website/App 4 Choose Mediation partner 5 Book campaign 6 Detect information 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. 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. 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 contact person. The trafficker books the Mobile campaigns in the ADTECH IQ user interface. 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. 2012-12-18 Page 8 of 216
ADTECH Display versus ADTECH Mobile Introduction This topics describes the differences between ADTECH Display and ADTECH Mobile Differences to ADTECH Display 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 Websites and 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 Information for App Developers. Manufacturer, device, size, carrier and OS: The ADTECH features keyword targeting, key value targeting and placement alias are used to pass certain mobile information 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. 2012-12-18 Page 9 of 216
ADTECH Mobile Feature List Introduction This topic describes which features are supported by the ADTECH Mobile solution. Features of ADTECH Mobile The following features are supported/ not supported by ADTECH Mobile: Features ADTECH Mobile ADTECH Analytics Campaign layers Click or transaction rate based banner optimization 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 2012-12-18 Page 10 of 216
Features Server side cookies ADTECH Mobile Server-to-server pixel Size detection Targeting by carrier Targeting by device and manufacturer Targeting by OS *not for custom domains ADTECH Mobile feature comparison for Mobile Web and Mobile App The following features are supported/ not supported by ADTECH Mobile for Mobile Web and Mobile App: Features Special banner formats/templates (e.g. fullscreen or expandable banner) Mobile Web Mobile App 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 2012-12-18 Page 11 of 216
Mobile Ad Request Mobile ad request image Sections 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 Value 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 selection The ADTECH Ad Server checks whether a campaign is available. 5 Ad response The ad response (campaign or default) is sent to the Mobile Ad Server. 5a 5b Check for Mediation Partner Mediation ad response (If mediation is activated and if ADTECH has returned a default) The Ad Server makes an ad request to the mediation network(s). (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. 2012-12-18 Page 12 of 216
Device Screen Size Categories Introduction 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 Marketing 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. Device size categories 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 2012-12-18 Page 13 of 216
MMA Mobile Web Banner Ad Sizes About the MMA 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 operators, 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. Standard mobile banner sizes 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. MMA recommended Mobile Web Banner Ad sizes 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 Notes: small 120x30 120x20 medium 168x42 168x28 large 216x54 216x36 x-large 300x75 300x50 xx-large 320x75 320x50 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 outlined 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. 2012-12-18 Page 14 of 216
Keyword, Key Value and Alias Introduction 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. Keyword 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. Key Value 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. 2012-12-18 Page 15 of 216
Alias 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 (alias=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 other1. 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 2012-12-18 Page 16 of 216
Request URLs with Keyword, Key Value and Alias Introduction This topic shows example request URL for EU and US that are passed from the device to the Mobile Ad Server and 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 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 Example Request URL US from Mobile Ad Server to Ad Server 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 URL sections The URL contains the following sections: Functionality Targeting Variable Example Description Keyword 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 information. Manufacturer, Device key rld-apple_iphone Apple, iphone Key value Carrier/OS kvmcarrier/ kvmos VODAFONE_UK/ VERIZON_US Vodafone UK/ Verizon USA Alias Size alias mobilesportsboxingandandroidbanner-top-4 4=XL device screen category 2012-12-18 Page 17 of 216
HTTP Header Information Introduction 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. Use case 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. X-Forward-For (XFF) 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. 2012-12-18 Page 18 of 216
Mediation Introduction When using ADTECH Mobile, it is possible to collaborate with a mediation partner. This topic describes what mediation is and how it is used. What is mediation? 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 mediation partner who fills the remnant inventory. For details see Mobile Ad Request on page 12. Publisher ID and mapping list 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 Publisher ID Mapping list Description A publisher ID is given by the mobile mediation partner and helps to identify a customer. 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 partner 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 separate 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 Mediation and key values 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. 2012-12-18 Page 19 of 216
Mediation and fullscreen banners 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 placements should be passed. If the mediation partner does not support mediation of fullscreen ads, the publisher must remove the placement from the mediation mapping list so that it will not be sent to the mediation partner. 2012-12-18 Page 20 of 216
More than One Mediation Partner Introduction When working with more than one mediation partner, there are currently two possible scenarios for the set-up: by priority by weight The two scenarios are described below. Priority order set-up 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. Weight set-up 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 repeats 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. Likewise, Mojiva is more likely to be called than InMobi. 2012-12-18 Page 21 of 216
Postclick Tracking Beacon Tags Introduction 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 Postclick Tracking documentation. Note: It is possible to have different postclick tracking beacon tag templates (e.g. for Display and for Mobile) in your network. Mobile beacon tag examples for US and EU 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 --> 2012-12-18 Page 22 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> <!-- Postclick Tracking Tag End --> 2012-12-18 Page 23 of 216
Chapter 2 Introduction ADTECH Mobile SDK This chapter describes the ADTECH Mobile SDK for app developers. In this chapter 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 2012-12-18 Page 24 of 216
2.1 General Information About the ADTECH Mobile SDK In this chapter 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 2012-12-18 Page 25 of 216
ADTECH Mobile SDK Release Notes Platform specific 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 2012-12-18 Page 26 of 216
Purpose and Contents of the ADTECH Mobile SDK Introduction 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 on websites versus mobile on apps 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 technical 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 procedures and structures regarding apps are found in the ADTECH Mobile Websites guide and not in the ADTECH Mobile for App Developers guide. Purpose 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 frameworks (like PhoneGap, Titanium etc.) will work with the ADTECH Mobile SDK, therefore we cannot offer any support for them. Contents 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 included 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 attribution for the 3 rd party libraries used by the SDK. You can find these libraries and their license statements in the License.txt file. 2012-12-18 Page 27 of 216
Responsibilities of the App Developer Tasks of the ADTECH Mobile SDK 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. Code modification 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. 2012-12-18 Page 28 of 216
Compliance with Advertising Standards Compliance overview 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 29 of 216
MRAID Compliance Mobile SDK MRAID Compliance The ADTECH Mobile SDK is compliant with the IAB standards and guidelines. MRAID http://www.iab.net/mraid, or Mobile Rich Media Ad Interface Definitions is the IAB http://www.iab.net/ Mobile Marketing Center of Excellence s project to define a common API for mobile rich media ads that will run in mobile 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 accelerometer, 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 20 th of October, 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. MRAID 1.0 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 focuses 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 complexity 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. 2012-12-18 Page 30 of 216
MRAID 2.0 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 31 of 216
ORMMA Compliance About ORMMA 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 32 of 216
VAST Compliance Introduction This topic describes on high level what VAST is and how the ADTECH Mobile SDK is related to it. What is VAST? 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 VAST 1.0 VAST 2.0 Description In 2008, the IAB introduced the first version of VAST to the video advertising marketplace, which has since been widely adopted throughout the industry. 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 writing. How the ADTECH Mobile SDK supports VAST 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 companion 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. 2012-12-18 Page 33 of 216
The ADTECH Mobile SDK Features and Properties Features and properties Category OS support Device support Placements Ad refresh Animations Properties Android versions 2.1 (update 1, API level 7) and higher are supported. 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. 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 support for devices using the armv7s architecture (iphone 5). The class that implements a placement (ATBannerView), extends the generic view class of each platform (RelativeLayout on Android 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. 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. When 2 ads switch each other in an ad container, usually the transition 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 2012-12-18 Page 34 of 216
Category Fail / Retry Interstitial Mediation Ad-enabled video player Properties 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 failures, the SDK stops fetching ads until the user calls the load method 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 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. If configured, the SDK can serve ads from other ad providers using their own SDKs internally. Using the VAST compliant video player provided by SDK the app developer can show video content (local or remote, progressive or streamed) and fetches and displays ad during playback as configured. 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 implementation specific on each platform (WebView on Android and UIVebWiew on ios) and because of this the restrictions on what can be displayed is dictated by the base container. 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 supported by the platform. 2012-12-18 Page 35 of 216
ADTECH Mobile SDK Feature Matrix for Different Platforms Ad display features Feature ios Android Windows Phone 7.5 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 Windows 8 Offline delivery features Feature ios Android Windows Phone 7.5 Caching of ADTECH static image ads Caching of ADTECH rich ads Caching of 3 rd party MRAID ads Cache disengageable on placement level Caching of fullscreen interstitials Track offline impressions, views, clicks Report offline impressions, views, clicks Windows 8 2012-12-18 Page 36 of 216
Mediation to 3 rd party SDKs SDK ios Android Windows Phone 7.5 AdMob iad Millenial Media Greystripe Vdopia Windows 8 2012-12-18 Page 37 of 216
Placement Configuration for the ADTECH Mobile SDK Introduction This topic shows the configuration that has to be provided for each placement. Placement configuration 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 2012-12-18 Page 38 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). The values Value Application name Network and subnetwork IDs Domain and domainforvideo Description 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. 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. 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 instance basis. 2012-12-18 Page 39 of 216
Value Alias Animation type Refresh interval Description 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 (outside of checking that it is not Null or an empty string, i.e. ""). The animation type can be configured per placement level and its purpose is to add a visual transition effect for 2 ads changing in one placement. 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. 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 refresh 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 40 of 216