ADTECH Mobile for App Developers

Transcription

User Guide
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
2012-12-18
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
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
2012-12-18
Glossary
216
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: [email protected]
URL: http://www.adtech.de/
2012-12-18
Page 6 of 216
Chapter 1
Framework and Technology
In this chapter
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.
2012-12-18
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 Mediation
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 contact person.
5
Book campaign
The trafficker books the Mobile campaigns in the ADTECH IQ user
interface.
6
Detect information
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.
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
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
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
Mobile
Web
Mobile
App
Special banner formats/templates (e.g. fullscreen 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
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
Check for Mediation Partner
(If mediation is activated and if ADTECH has returned a default)
The Ad Server makes an ad request to the mediation network(s).
5b
6
Mediation ad response
(If a mediation partner exists)
Ad delivery
The Mobile Ad Server delivers the ad.
The network sends the ad response to the Mobile Ad Server.
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
2012-12-18
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
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
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 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
• 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.
• 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...
optional
other8
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:
2012-12-18
Size key
Device Size
Category
1
S
2
M
3
L
4
XL
5
XXL
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
• 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.
Example Request URL
EU from device to
Mobile Ad Server
http://a.adtech.de/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;grp=[group];random=129906372986
Example Request URL
US from device to
Mobile Ad Server
http://a.adtechus.de/addyn/3.0/1119.1/0/0/0/ADTECH;loc=100;grp=[group];random=129906372986
Example Request URL
EU from Mobile Ad
Server to Ad Server
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
Manufacturer,
Device
key
rld-APPLE_IPHONE
Apple, iPhone
Key value
Carrier/OS
kvmcarrier/
kvmos
VODAFONE_UK/
VERIZON_US
Vodafone UK/
alias
mobilesportsboxingandandroidbanner-top-4
4=XL device screen
category
Alias
2012-12-18
Size
Verizon USA
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
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 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
2012-12-18
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.
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

<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>

Example User Tracking Beacon Tag EU
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>
2012-12-18
Page 22 of 216
Example Sales Beacon Tag US
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>
Example Sales Beacon Tag EU
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 23 of 216
Chapter 2
ADTECH Mobile SDK
Introduction
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 3rd 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 20th 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:
How the ADTECH
Mobile SDK supports
VAST
2012-12-18
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 writing.
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.
Page 33 of 216
The ADTECH Mobile SDK Features and Properties
Features and
properties
Category
Properties
OS support
• 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.
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 support 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 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.
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 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:
•
•
•
•
•
•
2012-12-18
slide left
slide right
slide top down
flip right
flip left
none
Page 34 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 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
• 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 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
Windows
8
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
Offline delivery
features
Feature
Caching of ADTECH static image ads
Caching of ADTECH rich ads
Caching of 3rd party MRAID ads
Cache disengageable on placement level
Caching of fullscreen interstitials
Track offline impressions, views, clicks
Report offline impressions, views, clicks
2012-12-18
Page 36 of 216
Mediation to 3rd party
SDKs
SDK
iOS
Android
Windows
Phone 7.5
Windows
8
AdMob
iAd
Millenial Media
Greystripe
Vdopia
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:
•
•
•
•
•
•
•
2012-12-18
application name
network ID
subnetwork ID
domain
animation type
ad refresh interval
allow location services
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
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 domainForVideo
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
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 (outside 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 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.
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 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
Value
Description
AllowLocationServices setting
This setting is used to allow or disallow the ADTECH Mobile SDK using
the Location Services (iOS feature only). The app developer must explicitly give his consent for the SDK to use the device’s location, either
through this setting in the configuration file, or through the configuration 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 additional 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 configuration.
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 41 of 216
The values for video
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 presented 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 seconds, after which to start displaying the overlay
• duration: the time interval of content playback, specified in seconds, 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 seconds 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 42 of 216
Value
Description
The video dimension
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 bitrate. 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 specification, to follow until the SDK gives up obtaining the video ads.
The default value is 3.
2012-12-18
Page 43 of 216
Tracking Unique Devices with the Mobile SDK
Identifying unique
devices
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.
Unique device ID in
Android
Each mobile device has its own, fixed identification property and this identifies a device cross-application. For Android the UDID of the device.
Unique device ID in
iOS
For iOS before 6.0 or ADTECH Mobile SDK versions before 3.0, a unique string is generated 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 request URL. (E.g. appguid=faf5341a39919352a4f9bde4d6de5396). Each application creates its own identifier.
Starting iOS 6.0 and ADTECH Mobile SDK version 3.0, the OS provided advertisingIdentifier 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.
2012-12-18
Page 44 of 216
Logging the ADTECH Mobile SDK Activity in the Console
About logging
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
2012-12-18
Page 45 of 216
Caching and Offline Display
Purpose
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 experience 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.
Configuration
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 access 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.
Offline display /
offline event tracking
& reporting
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.
Limitations
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 application using the SDK. In order to reduce this effect, only one networking connection is
used at one time (per cache). The same effect can happen when there are cached offline 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 leftover/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 display is done for them, but because of unexpected application terminations, leftover
resources can remain stored until the next application run.
2012-12-18
Page 46 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 successfully 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 differences, 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 47 of 216
Video Ads in the ADTECH Mobile SDK
Introduction
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.
Usage
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 configuration made available to it.
A typical use case for using video player would follow these steps:
Step
Behavior
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.
3
Configure the type of ads to show (linear ads and/or overlays).
4
Set the content the user chose or needs to see. This can be a local or remote media file. It can also be a stream based content.
5
Play the content or allow the user to play it when he/she decides to.
Depending on the configuration provided, the player will fetch internally the ads and
show them at appropriate times.
For example, if a pre-roll ad is configured, the player will fetch the pre-roll ad from the
server and show it before the actual video content is being played back.
The player will prepare and play the pre-roll before the content gets a chance to play.
Once it is done with the pre-roll ad the player will continue with playing the content.
Similarly, for mid-roll ads, the content being played back is paused, the mid-roll ad is
shown and once it is done the content resume playback.
Playback of the linear video ads cannot be skipped during them being presented. During playback of ad, the user can engage it by tapping the video view. If so configured
server-side, this will show a fullscreen in-app browser with a landing page. Playback of
the content is paused while the user interacts with the browser and its content. Once
the browser is dismissed, playback of the content resumes (if there still is content to
show). The remaining part of the video ad that was engaged is not shown after the
user dismisses the browser and playback skips to the actual content.
2012-12-18
Page 48 of 216
Overlays (non-linear ads) are shown as banners on top of the video being played back.
They do not stop video playback, unless the user engages them. When tapped, playback is paused and the landing page is shown using the in-app browser. After closing
the in-app browser, the overlay is removed from the screen.
The overlays have a duration of being displayed. The SDK takes care of presenting
them at the configured time and keeping them on screen until the duration elapses.
The duration for showing overlays is measured in number of seconds of actual content
playback. This means that if a linear ad (mid-roll) pauses the content playback or the
user pauses the content manually, the time spent with the player in the paused state
does not count towards the duration of the overlay being shown. Overlays are not
shown while a linear ad is presented.
Overlays can be configured to be dismiss-able by the user or not. Additionally, you can
configure an overlay to be dismiss-able only after a specified amount of time. If an
overlay is dismiss-able, but not from the start, a countdown will be shown to let the
user know how long until the overlay can be dismissed. The default behavior for an
overlay is to wait half the duration of being displayed until it becomes dismiss-able.
If an error occurs during fetching or preparation of the video ads, including the overlays, these ads will be skipped and will not interrupt the video content. The error reasons will be logged to the console.
The user can interact with the player at any time when playing the video content if
allowed by the application developer. The SDK adds no limitation to the controls
available at playback time. However, during video ad playback, no controls are shown
to prevent the user from skipping the ads by fast-forwarding and also to allow for an
interrupted and un-obscured experience. Playback control can still be performing programmatically during video ad playback but will be applied to the content and not the
video ad. Exceptions are the play, pause, stop and fullscreen calls that will apply to the
ad itself.
Calling stop will stop playback of both the content video and the linear ads. When play
is called again, only the ads that have not been shown before will be presented.
Changing the content of the player at any time during its life-cycle, will cause the player to stop the playback (if ongoing) of both the video ads and the content and return
the player to its initial state. Calling play at this time will cause a pre-roll to be shown,
if configured.
Video ads fullscreen state mimics the state set on the content. If the content was fullscreen before the ad was shown, the ad will play fullscreen as well. If the video content playback was “windowed” before the ad, the ad will show presented in the same
way.
Tracking
All the events relevant for linear ads that are defined in the VAST specification are
supported and reported live during the playback of the video ads.
These include impressions, videoClicks, start, first quartile, mid point, third quartile,
complete, mute, unmute, fullscreen, pause, resume events. In case there is some
problem showing the ad, error events are generated and reported.
For overlays, the following events are tracked and reported: creative view, start, first
quartile, mid point, third quartile, complete and close.
The application needs to have Internet connectivity in order for the events to be reported.
2012-12-18
Page 49 of 216
Limitations
• If the VAST document returned by the server contains multiple ads, only the first
one will be used.
• The data from the wrappers will be merged with the first linear ad available in the
VAST response document.
2012-12-18
Page 50 of 216
Mediation in the ADTECH Mobile SDK
About mediation
This topic describes the 3rd party ad mediation capabilities of the ADTECH Mobile SDK.
Mediation to 3rd parties is triggered only, when ADTECH is delivering a default.
There are basically 2 different types of mediation:
• Mediation of ads where a 3rd party SDK is involved on the client-side. Displaying the
advertisement is taking place through the 3rd party SDK.
• Mediation of ads that are served directly through our mobile adserver. Image-ads
or MRAID ads can be delivered from mediation partners that are connected to our
mobile adserver.
The configuration of the mediation can be set on a placement level, either via priority
or percentage. A combination of both is currently not supported.
Configuration changes via IQ are currently not supported. To change your mediation
configuration please reach out to your ADTECH CS contact person.
Examples
Examples for a valid set up could be the following:
• 1. ADTECH, 2. AdMob 50% / iAd 50%
• 1. ADTECH, 2. Millenial Media, 3. Greystripe
An invalid configuration example is the following:
• 1. ADTECH, 2. Greystripe, 3. AdMob 20% / iAd 80%
Mediated 3rd party
ads
The ADTECH Mobile SDK has the capability to mediate ads from a series of 3rd party ad
providers. See the Android and iOS specific Mediation sections to note the supported
3rd party providers and steps needed to enable them in your application:
• Android: How to Use Mediation for Third Party Advertisement SDKs in Android on
page 146
• iOS: How to Use Mediation for Third Party Advertisement SDKs in iOS on page 105
Tracking & reporting
events on the 3rd
party mediated ads
Each 3rd party ad can track and report events to its specific reporting server. Additionally to this, the ADTECH Mobile SDK tracks events happening on the mediated 3rd party
ads and reports them to the ADTECH backend for further processing. The events collected by the ADTECH Mobile SDK depend on what the SDK of the 3rd party ad exposes
publicly and what can be deducted by object behavior at runtime.
The events collected from the 3rd party mediated ads are categorized into:
•
•
•
•
2012-12-18
impression
view
click
failure
Page 51 of 216
2.2
ADTECH Mobile SDK: iOS
In this chapter
Topic
Page
Getting Started with the ADTECH Mobile SDK for iOS ......................................... 53
How to Use the Mobile SDK in iOS ....................................................................... 63
The Public Interface (iOS) ..................................................................................... 82
How to Use Mediation for Third Party Advertisement SDKs in iOS.................... 105
2012-12-18
Page 52 of 216
2.2.1
In this section
Getting Started with the ADTECH Mobile SDK for iOS
Topic
Page
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
2012-12-18
Page 53 of 216
How to Integrate the ADTECH Mobile SDK into Your iOS App
Introduction
This topic serves as a guideline for app developers on how to integrate the ADTECH
Mobile SDK into iOS apps.
Prerequisite
To use the ADTECH Mobile SDK for iOS, iOS version 3.1 or higher is required. For video
ads, 4.0 or higher is required.
Starting release 2.2.3 of the SDK, the armv6 architecture is not supported anymore.
This means, application using the newer versions of the SDK cannot be deployed on
devices that have the armv6 CPU architecture (the original iPhone, iPhone 3G, first and
second generation iPod touch).
Content of the
ADTECHMobileSDK_i
OS_3.0.1.zip
How to add the
ADTECHMobileSDK.fr
amework into your
Xcode application
Folder
Description
Framework
Folder containing the ADTECHMobileSDK.framework and the ADTECHLocalizable.strings file.
Docs
Folder containing the de.adtech.ADTECHMobileSDK-3.0.1.xar XCode
documentation for the SDK interface.
Sample
Folder containing an ADTECHSampleApp project where the SDK is used.
README.txt
File containing install instructions.
LICENSE.txt
File containing the license of the third party code used by the
ADTECHMobileSDK.
Step
1
Action
Copy the ADTECHMobileSDK.framework into the folder where your app resides:
Notes:
• This step is not mandatory but it is a good practice to have the 3rd party
frameworks located together with your app resources.
• Make sure when you unpack the archive that the symbolic links are not broken. Using the default Mac OS unzipping tool is recommended.
2012-12-18
Page 54 of 216
Step
2
Action
Include the ADTECHMobileSKD.framework into the project.
In XCode:
• Go to Project > Target > Build Phases and select the Link Binary With Libraries tab.
• Click the + button, click the Add Other… button, and select the
ADTECHMobileSDK.framework:
• Click Open.
Result: The ADTECHMobileSDK.framework is now linked against your app, and
you can access and use all of its classes defined in the public interface.
2012-12-18
Page 55 of 216
Step
3
Action
Include the additional iOS frameworks that the SDK uses.
In XCode:
• Go to Project > Target > Build Phases and select the Link Binary With Libraries tab.
• Click the + button.
• Add the following iOS libraries:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
AdSupport.framework (optional)
AudioToolbox.framework
AVFoundation.framework
CFNetwork.framework
CoreData.framework
CoreGraphics.framework
CoreLocation.framework
CoreMedia.framework
CoreMotion.framework
CoreTelephony.framework (optional)
EventKit.framework
EventKitUI.framework
MediaPlayer.framework
MessageUI.framework
MobileCoreServices.framework
QuartzCore.framework
Security.framework
SystemConfiguration.framework
libxml2.dylib
libz.dylib
Additionally, if you are using a 3rd party SDK for mediation you need to add the
following frameworks as well:
• iAd: iAd.framework
• Millennial Media: Foundation.framework
• Greystripe: OpenAL.framework, libsqlite3.dylib
4
Make sure your project is targeted for an iOS version 3.1 or above. If you are
planning on using video ads, you need iOS 4.0 or above.
In XCode:
• Go to Project > Target > Build Settings.
• Search for iOS Deployment Target.
• Make sure it is set to 3.1 or a value above it (e.g. 4.0).
5
Include the ADTECHMobileSDK.h header into your project.
Including the ADTECHMobileSDK.h header into your apps precompiled header file
will ensure you have access to the Adtech public classes from anywhere in your
app.
For this, open your projects .pch file (e.g. YourApp-Prefix.pch) and add the following line:
#import <ADTECHMobileSDK/ADTECHMobileSDK.h>
2012-12-18
Page 56 of 216
Step
6
Action
Add the resources needed by the SDK to the project.
In XCode:
• Select the group from your app where you keep the resources.
• Right click and select Add Files to "Your App".
• Navigate to the ADTECHMobileSDK.framework.
• From the Resources folder select the ADTECHAdConfiguration.plist and
ADTECHMobileSDK.bundle files.
• Click Add.
• Optionally, add to your project the ADTECHLocalizable.strings. This will allow
you to provide localized message that are shown to the user by the SDK. By
default all the messages are in English.
7
Activate the ObjC linker flag.
The SDK internally uses categories so for this reason the ObjC flag must be set for
the linker.
In XCode:
• Go to Project > Target > Build Settings,
• Search for Other Linker Flags.
• Add the -ObjC flag.
For more details see
http://developer.apple.com/library/mac/#qa/qa1490/_index.html
http://developer.apple.com/library/mac/#qa/qa1490/_index.html.
2012-12-18
Page 57 of 216
Step
8
Action
Compile your app.
Result: You can start adding the ADTECH banners and interstitials into your app.
2012-12-18
Page 58 of 216
How to Update the ADTECH Mobile SDK to a Newer Version (iOS)
Introduction
If you are already using a version of the ADTECH Mobile SDK and a new one is released, we recommend that you update your application with the new version. New
releases introduce features, improvements and bug fixes based on your valuable input.
All the releases made so far are backwards compatible with the older versions, meaning that you do not have to change your code in order for it to work with the new version. If you do not want to use the newly introduced features that need coding, you
will not have to change anything in your application’s code. You will get however the
improvements and fixes.
How to Update the
ADTECH Mobile SDK
to a newer version
Step
Action
1
Obtain the zip file with the new version of the ADTECH Mobile SDK.
2
Unpack the archive somewhere on your computer.
3
Remove from your project the ADTECHMobileSDK.framework and the additional
resources you are using from it. These include the ADTECHAdConfiguration.plist,
ADTECHMobileSDK.bundle and the ADTECHLocalizable.strings.
Note: Take care when under version control, not to remove relevant version control related resources.
4
Copy the contents of the Framework folder (namely the
ADTECHMobileSDK.framework and the ADTECHLocalizable.strings file) to where
the old version is placed in your project, overwriting it.
5
Add again to your project the framework and the resources that you removed at
step 3, from inside the new framework.
6
Put back in the ADTECHAdConfiguration.plist file your default configuration details.
7
Check the version specific update notes (see below in this topic) and perform the
steps laid down there (if any).
8
Do a clean rebuild of your application and give it a go!
That’s it! You should now be using the newer version of the ADTECH Mobile SDK.
Note: You can simplify steps 3, 4 and 5 by just overwriting the old framework files with
the new ones, but this can have the side effect of not removing resources from the
framework that might have gone unused in the newer version. They will not harm your
application, but they might increase its size a bit.
2012-12-18
Page 59 of 216
Version specific
update notes
Updates to specific versions might require you to do some additional steps to the one
laid down above. If you are updating from an old version to a new one and there have
been other versions in between, you might have to perform the steps incrementally
from the old version to the target version by going through all the intermediary releases.
Update from 2.0 to 2.1
• Add to the list of system frameworks that your application uses the EventKitUI.framework.
Update from 2.1 to 2.2
• Add to the list of system frameworks that your application uses the AudioToolbox.framework, AVFoundation.framework, CoreMedia.framework and
libxml2.dylib.
Update from 2.2 to 2.2.3
• Starting release 2.2.3, the armv6 architecture is not supported anymore. 2.2.3
brings support for armv7s enabled devices (currently, the iPhone 5).
Update from 2.2.3 to 3.0
• Add to the list of system frameworks that your application uses the AdSupport.framework. Set its target membership to optional.
2012-12-18
Page 60 of 216
ADTECH Mobile SDK Release Notes (iOS)
Release 3.0.1
New features
• Support for SDK handling of landing page URLs, instead of the web browser.
Improvements
• Ads that are greater than the web view they are contained in can be scrolled
• Better support for facetime calls
Maintenance
• Fixed cannot set alarm with relative value to the starting date for calendar events
• Other small bug fixes, mainly related to MRAID 2.0 support
Release 3.0
New features
• Support for MRAID2.0
• For tracking, using the advertisingIdentifier introduced in iOS 6.0
• Not tracking anymore when the user limits ad tracking in the device settings
Maintenance
• Fixed issues when running on iOS 6.0
• Stability improvements
Release 2.2.4
Maintenance
• Fixed video not shown from MRAID interstitials
Release 2.2.3
New features
• Full support for ORMMA 1.0 and ORMMA 2.0 methods.
Improvements
• Support for armv7s architecture (iPhone 5)
Maintenance
• Fixed video overlays not shown on iOS 6
• Fixed media player launched multiple times from in-app browser on iOS 6
• Fixed additional ad requests sent out when cacheSize is 0 and setVisible is
called immediately after load
• Other minor bugfixes
2012-12-18
Page 61 of 216
Release 2.2.1
New feature
• Auto banner-resize
Maintenance
• Several bugs have been fixed
For the detailed changes in the API see the README.txt file in the .zip file.
Release 2.2
New features
• Support for VAST compliant video ads using the new public video player component
• Linear video ads (pre-, mid- and post-roll) are supported
• Non-linear video ads (image ad overlays) are supported. Image ads can be
shown during content playback as configured by the app developer
Maintenance
• Fixed banners start loading and showing ads when visibility is set to yes before
calling load
Release 2.1
New features
• Support for 3rd party SDKs: AdMob, iAd, Millennial, Vdopia, GreyStripe
Improvements
• Allow the app-developer to control the ad’s viewable state
Maintenance
• Several small issues have been fixed
2012-12-18
Page 62 of 216
2.2.2
In this section
How to Use the Mobile SDK in iOS
Topic
Page
How to Add a Banner Using Interface Builder (iOS) ............................................. 64
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
2012-12-18
Page 63 of 216
How to Add a Banner Using Interface Builder (iOS)
Introduction
Procedure
This topic describes the steps necessary for adding a banner to your iOS app using the
Interface Builder.
Step
1
Action
Add the banner:
• Go to your view controllers XIB file and open it in Interface Builder.
• Grab a UIView element and add it as a subview or your view controller’s view.
• Set the newly added views Class to be of type ATBannerView.
2
Configure the banner:
• The most common size for a banner is 320x50, but you can set up any size as
needed. You want to make sure that the banner size matches the size of the
creatives set up on the ADTECH IQ server. This will ensure that the ad fills up
the whole banner real-estate and that the end user will have a good user experience.
• You can set up any additional properties just like you would set up a regular
UIView element (e.g. background color).
• One thing you want to make sure is that the autoresizing mask properties are
correctly set up.
• If you are going to display ads that do not react to container size changes, it is
a good idea to disable auto-stretching the banner on rotation.
2012-12-18
Page 64 of 216
Step
3
Action
Set the outlet:
You will need to be able to call methods from code on the banner and for this
reason you will need to set up an outlet reference to the banner from your view
controller.
Waking up the
banner to life
Once the UI is set up and you have a reference to the banner, you will need to set up
its configuration’s alias property and send the banner the load message. By default all
the config properties needed by the banner will be loaded at creation time using the
values you defined in the ADTECHAdConfiguration.plist file. Exception to this is
the alias, that needs to be individual for each banner.
The ADTECH Mobile SDK needs to know who is the banners parent view controller and
for this you need to set the banners viewController property. Failing to do so the banner will not start up when you tell him to load. Additionally if you would like to be
informed of different events in the banners lifecycle (e.g. next ad loaded, failed to load
ad, should suspend application, ...) then you need to set the banners delegate. Usually
this is the same view controller thats view contains the banner.
You should do this in the viewDidLoad method of your view controller:
- (void)viewDidLoad
{
[super viewDidLoad];
adtechBanner.configuration.alias = @"home-top-5";
adtechBanner.viewController = self;
adtechBanner.delegate = self;
//adtechBanner.allowLocationsServices = YES; //Optionally allow usage of the Location
Services.
[adtechBanner load];
}
2012-12-18
Page 65 of 216
Getting notified
about state changes
in the banner
If you set the delegate to the banner, you must ensure it implements the ATBannerViewDelegate protocol. Add this protocol to your view controllers interface definition and optionally implement some of the methods defined in the protocol. At
least shouldSuspendForAd and shouldResumeForAd method should be implemented so that you know when the host app should be suspended and resumed. (e.g.
the user is playing a game then sees an attractive ad, it clicks on it and the ad expands
covering the whole UI – the game going on in the host app should be suspended while
the banner is expanded)
// in your view controllers header file
@interface YourAppViewController : UIViewController <ATBannerViewDelegate>
// in the view controllers m file
#pragma mark - ATBannerViewDelegate
- (void)shouldSuspendForAd:(ATBannerView*)view
{
// if needed, suspend the activity of the host application
}
- (void)shouldResumeForAd:(ATBannerView*)view
{
// resume the activity of the host application
}
- (void)willLeaveApplicationForAd:(ATBannerView*)view
{
// the ad triggered the app to enter background (e.g. the user clicked a URL in the ad)
// you should save your apps state at this point
}
Releasing the banner
You want to make sure the banner is released in the viewDidUnload method (this will
be called when the view is unloaded, usually as a result of a memory warning). Also
make sure when the view controller deallocates that the banner is deallocated as well.
- (void)viewDidUnload
{
[super viewDidUnload];
self.adtechBanner = nil;
}
- (void)dealloc
{
[adtechBanner release];
[super dealloc];
}
2012-12-18
Page 66 of 216
Setting the visibility
flag of the banner
One last thing you need to do is keep the banners visibility flag up to date. This is important so that the banner knows when to work for you and refresh the ads and when
to pause. Failing to set the visibility flag when needed, you might have your users miss
important ads for their interests.
Since the banner is a subview of the view controllers view, it will be visible when this is
visible and hidden when this is not visible. For this reason the best place to set the
visibility flag is on viewDidDisappear and viewDidApperar.
- (void)viewDidDisappear:(BOOL)animated
{
[super viewDidDisappear:animated];
adtechBanner.visible = NO;
}
- (void)viewDidAppear:(BOOL)animated
{
adtechBanner.visible = YES;
[super viewDidAppear:animated];
}
Note: While the ad is presenting a modal screen, like when it is expanded or the user
tapped on the banner and the landing page is shown, setting the visibility of the ad
has no effect. It is only in the collapsed, banner state that the visibility can be changed.
Once these steps are completed you are good to go. The banner is correctly set up and
loading is started.
2012-12-18
Page 67 of 216
How to Add a Banner Entirely from Code (iOS)
Introduction
This topic describes the banner set-up process if you do not want to use the Interface
Builder.
Adding the banner as
a member of your
class
{
ATBannerView *adtechBanner;
}
@end
Configuring and
loading the banner
The indicated place to initialize, setup and load the banner is the viewDidLoad
method, but you can do this wherever is most suitable for your app. The key thing to
be careful about is that you should only add the banner as a subview when your view
controller’s view is initialized.
- (void)viewDidLoad
{
adtechBanner = [[ATBannerView alloc] initWithFrame:CGRectMake(0,0,320,50)];
adtechBanner.configuration.alias = @"home-top-5";
adtechBanner.viewController = self;
adtechBanner.delegate = self;
// add the banner as a subview of your view controllers view
[self.view addSubview:adtechBanner];
[adtechBanner load];
}
Releasing the banner
You want to make sure the banner is released in the viewDidUnload method (this
will be called when the view is unloaded, usually as a result of a memory warning).
Also make sure when the view controller deallocates that the banner is deallocated as
well.
- (void)viewDidUnload
{
[super viewDidUnload];
self.adtechBanner = nil;
}
- (void)dealloc
{
[adtechBanner release];
[super dealloc];
}
2012-12-18
Page 68 of 216
Setting the visibility
flag of the banner
The last thing you need to worry about is keeping the banners visibility flag up to date.
This is important so that the banner knows when to work for you and refresh the ads
and when to pause. Failing to set the visibility flag when needed, you might have your
users miss important ads for their interests.
Since the banner is a subview of the view controllers view, it will be visible when this is
visible and hidden when this is not visible. For this reason the best place to set the
visibility flag is on viewDidDisappear and viewDidApperar.
- (void)viewDidDisappear:(BOOL)animated
{
[super viewDidDisappear:animated];
adtechBanner.visible = NO;
}
- (void)viewDidAppear:(BOOL)animated
{
adtechBanner.visible = YES;
[super viewDidAppear:animated];
}
Getting notified
about state changes
in the banner
If you set the delegate to the banner, you must ensure it implements the ATBannerViewDelegate protocol. Add this protocol to your view controllers interface definition
and optionally implement some of the methods defined in the protocol. At least shouldSuspendForAd and shouldResumeForAd method should be implemented so that you
know when the host app should be suspended and resumed. (e.g. the user is playing a game
then sees an attractive ad, it clicks on it and the ad expands covering the whole UI – the
game going on in the host app should be suspended while the banner is expanded)
// in your view controllers header file
// in the view controllers m file
#pragma mark - ATBannerViewDelegate
- (void)shouldSuspendForAd:(ATBannerView*)view
{
// if needed, suspend the activity of the host application
}
- (void)shouldResumeForAd:(ATBannerView*)view
{
// resume the activity of the host application
}
- (void)willLeaveApplicationForAd:(ATBannerView*)view
{
// the ad triggered the app to enter background (e.g. the user clicked a URL in the ad)
// you should save your apps state at this point
}
Once these steps are completed you are good to go. The banner is correctly set up and fired.
2012-12-18
Page 69 of 216
How to Add an Interstitial (iOS)
Introduction
This topic shows how to integrate an interstitial view when navigating between two
screens.
Note: For MRAID 2.0 ads, in order for an interstitial to be shown in a specific interface
orientation (like landscape) when the device might be in a different one, the ad must
set the orientationProperties before the ready event is triggered by the SDK.
This is the responsibility of the ad developer. If not, the interstitial will be presented in
the orientation of the device at the time of it being shown.
Adding the banner as
a member of your
class
@interface YourAppViewController : UIViewController <ATInterstitialViewDelegate>
{
ATInterstitialView *interstitial;
}
@end
Configuring and
loading the
interstitial
The indicated place to load an interstitial is when you create a new screen. Depending
on your needs, you might want to show the interstitial each time when you enter the
screen or only once. You should start loading the interstitial inside your viewDidLoad
method. After the interstitial is loaded (you get notified of this through the delegate)
you need to call present on it to be presented.
The interstitial is presented modally over the viewController you configured it with.
This means that when it is presented, your viewWillDisapper: method gets called and
viewWillAppear: is called when the interstitial is dismissed. It a good idea not to
automatically present the interstitial on viewWillAppear: or to destroy it on
viewWillDisappear:, because this will lead to infinite loop and early dismisses of
the interstitial.
- (void)viewDidLoad
{
// create an interstitial view
interstitial = [[ATInterstitialView alloc] init];
interstitial.delegate = self;
interstitial.viewController = self;
// configure it
interstitial.configuration.alias = @"interstitial-middle-5";
interstitial.configuration.networkID = 23;
interstitial.configuration.subNetworkID = 10;
interstitial.configuration.refreshInterval = 10;
// start the load process, you'll get callback on the delegate once the interstitial is loaded
// for a better user experience you should wait untill the interstitial is loaded before you
display it
[interstitial load];
}
#pragma mark - ATInterstitialViewDelegate
2012-12-18
Page 70 of 216
- (void)didSuccessfullyFetchInterstitialAd:(ATInterstitialView*)view
{
[view present];
}
- (void)didHideInterstitialAd:(ATInterstitialView *)view
{
[interstitial release];
interstitial = nil;
}
2012-12-18
Page 71 of 216
Banner and Interstitial Configuration (iOS)
Introduction
This topic explains the concepts related to the banner view and interstitial view configuration.
Default request
configuration
When a banner or an interstitial view is created, the configuration is pre-filled with
some default values. These values are taken from the ADTECHAdConfiguration.plist file and they serve as a common base for the ATBannerView and
ATInterstitialView. This configuration is used internally by the ADTECH Mobile
SDK when the ad request is composed and sent. Failing to provide a valid configuration
will result in a broken request.
Configuration that is specific to each banner is not placed in the property list file, but it
can and must be set at runtime before calling the load method. Such a configuration
property for example is the alias and failing to set it will result in ad request failure and
the banner remaining empty.
For a more detailed overview on the default configuration see Ad Configuration for the
ADTECH Mobile SDK on page 38.
The delegate and the
parent view
controller
The ADTECH Mobile SDK needs to know the parent view controller where it is integrated so failing to set it will cause the ad request not to fire. Setting the delegate
however is optional but recommended.
The ATBannerViewDelegate methods inform the ad on different states that the
banner goes through. The developer can and should react on these callbacks because
they are called before the banner impacts the app (e.g. expanding over the whole UI,
exiting the app to react on a URL change, initiating a call or SMS, loading the external
Google Maps app is it is installed …)
The ATInterstitialViewDelegate is even more important because it will signal
to the developer when the interstitial ad is loaded and ready to be displayed. This allows the developer to show the interstitial when it is loaded and leads to improved
user experience.
Enabling/disabling
banners that resize to
ad’s image size
When a banner serves simple image ads (not MRAID or ORMMA ads), you can have
the banner resize itself to fit the size of the image inside the ad, so that the ads look
well aligned inside the area reserved for the banner. This is useful when you expect
images of different sizes being deliver to the application. Before the banner resizes
itself, its delegate gets a call to willResizeAd:toSize: and, after it is done resizing, one to
didResizeAd:toSize: so that the application has a chance of resizing its own content to
fit well with the banner.
To enable this behaviour, set the property enableImageBannerResize to YES in
the banner configuration. By default its value is NO.
2012-12-18
Page 72 of 216
Enabling/disabling
SDK handling of
landing page URLs
For image ads (not MRAID or ORMMA compliant ones), when a banner, interstitial or
video ad is touched by the user, the normal behaviour is to open the in-app browser
and let it handle showing the landing page. In most instances the URL that should be
loaded in the browser, is not pointing to the actual landing page but redirects to it. If
the landing page should happen to be a special URI (i.e tel;. sms:, mailto:, itms://, etc.)
which can be handled by the OS, the browser will launch the appropriate native application to handle it. In this case, when returning to the application, the user is presented a blank page in the in-app browser. The user has to close this page in order to
return to the application content.
Application developers might wish to avoid having the users perform this extra step.
You can let the SDK perform an analysis of the landing page URL and take the appropriate action to show it, instead of delegating the task to the in-app browser. This prevents showing the blank page for the URIs with platform specific schemes. To enable
this behaviour, set the value of the property openLandingPagesThroughBrowser
to NO. By default this value is YES and it means that landing page URLs are handled by
the in-app browser.
Please take note that requesting the SDK to handle the URLs will add a small delay
between the time the user touches the ad and taking the action needed (like showing
the landing web page, or opening the AppStore application).
You can also set a default value for the property for all instances of ads using the
ADTECHAdConfiguration.plist file.
2012-12-18
Page 73 of 216
How to Use Video Ads (iOS)
Adding the video
player as a member
of your class
@interface YourAppViewController : UIViewController
{
ATMoviePlayerController *moviePlayerController;
}
@end
Initializing and
configuring the
player
- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil
{
self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
if (self)
{
// Add here your additional initialization code
moviePlayerController = [[ATMoviePlayerController alloc]
initWithContentURL:YOUR_CONTENT_URL];
moviePlayerController.presentingViewController = self;
ATVideoAdConfiguration *configuration = [[[ATVideoAdConfiguration alloc] init]
autorelease];
configuration.networkID = YOUR_NETWORK_ID; // if different from the default value set
in the ADTECHAdConfiguration.plist file
configuration.subNetworkID = YOUR_SUB_NETWORK_ID; // if different from the default value
set in the ADTECHAdConfiguration.plist file
configuration.alias = YOUR_ALIAS;
[configuration enableAdType:kATVideoAdPreRoll]; // Choose one or more
[configuration enableAdType:kATVideoAdMidRoll];
[configuration enableAdType:kATVideoAdPostRoll];
moviePlayerController.configuration = configuration;
[moviePlayerController prepareToPlay];
}
}
- (void)dealloc
{
[moviePlayerController stop];
[moviePlayerController release];
// Add here your additional release code
[super dealloc];
}
2012-12-18
Page 74 of 216
Showing the video
player view on screen
- (void)viewDidLoad
{
moviePlayerController.view.frame = YOUR_FRAME;
moviePlayerController.view.autoresizingMask = YOUR_AUTO_RESIZING_MASK;
[self.view addSubview:moviePlayerController.view];
}
Starting playback
Playback can be started at any time by calling
[moviePlayerController play];
or by letting the user start playback using the controls embedded on the player view.
You can register for all the notifications provided by the MPMoviePlayerController
system class and you can use any of the public methods and properties provided by it,
with the exception of the shouldAutoplay property. Autoplay is not allowed on ATMoviePlayerController instances.
2012-12-18
Page 75 of 216
How to Set the SDK Log Level (iOS)
Introduction
The ADTECH Mobile SDK has the capability to log different type of events. The developer can control this refinement by using the setLoggingLevel class method from
the ATBaseConfiguration class. The developer can control what and when the
ADTECH Mobile SDK should output logs. For example the developer could turn OFF
logging for release builds and turned in ON for debug builds. When the logging is ON,
the developer can control the level of desired logging. It may choose to log only errors,
errors and warnings or even fully turn on logging to verbose.
For details see iOS Class: ATBaseConfiguration on page 88 and the ATLogLevel enum
described in iOS Enums on page 102.
Example
A typical place where you would set the logging level is an early entry point into the
app like the for example the app:didFinishLaunchingWithOptions: method.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary
*)launchOptions
{
self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]
autorelease];
self.viewController = [[[YourAppViewController alloc]
initWithNibName:@"YourAppViewController" bundle:nil] autorelease];
self.window.rootViewController = self.viewController;
[self.window makeKeyAndVisible];
// turn OFF logging: nothing is logged
[ATBaseConfiguration setLoggingLevel:kATLogOff];
// turn ON logging: errors, warnings and general info is logges
[ATBaseConfiguration setLoggingLevel:kATLogInfo];
return YES;
}
2012-12-18
Page 76 of 216
How to Add Additional Key Value Parameters to the Ad Configuration (iOS)
Introduction
This topic shows how the developer can use custom user defined key value parameters to configure the banner or the interstitial.
Purpose of using
custom user defined
key value parameters
Beside the predefined ad configuration properties the user can add additional 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
configuration.
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.
Adding and removing
user defined key
values
The ATAdConfiguration contains a set of specialized methods for adding and removing key value pairs to the banner or interstitial configuration. The user can at any
time inspect the set of custom keys already defined and also inspect the values stored
under those keys. A key can store not only one but multiple values. Trying to add values with a key that already exists, the value will not be duplicated in the configuration
and the values will be appended to the already existing ones. In case a value repeats
itself it will be ignored.
Validation
When adding key value pairs, the ADTECH Mobile SDK does a validation and excludes
the ones that do not conform. As a result the methods will return with NO and an error will be generated. On failure a warning will also be logged.
• The maximum number of key value pairs that can be used on one ad is 26. If you
try to add more key values, a warning is logged and an error generated.
• As a general consideration, this key value pairs will be used for creating the ad request URL that has a length limitation of 4096. It might be that although the above
constraints are kept, still the URL to be too long (e.g. adding one key value pair,
where the value is an array with 128 tokens each with 48 chars). This will be ignored at URL construction and you will get a warning.
• The order of the value tokens is not guaranteed when the URL is constructed. The
order might be different from that of the input array.
2012-12-18
Page 77 of 216
Code sample 1:
Adding a list of
countries
NSError *error = nil;
BOOL success = [adtechBanner.configuration addUserKey:@"Country"
values:[NSArray
arrayWithObjects:@"DE",@"US",@"FR",nil]
error:&error];
if (!success)
{
// digest the error and resolve it if necessary
}
Code sample 2:
Manipulating the
countries
// inspecting all the user defined keys
NSArray *keys = [adtechBanner.configuration allUserKeys];
// inspecting all values for a given key
NSArray *countries = [adtechBanner.configuration valuesForKey:@"Country"];
// remove France from the countries list
[adtechBanner.configuration removeValue:@"FR" forKey:@"Country" error:nil];
// remove all the country values
[adtechBanner.configuration removeUserKey:@"Country"];
2012-12-18
Page 78 of 216
How to Localize Messages Presented from the SDK (iOS)
Localizing messages
presented from the
SDK
2012-12-18
To present localized versions of the messages presented to the user you need to add
to you project the ADTECHLocalizable.strings file that you can find in the
Framework folder inside the archive. You then need to localize this file for every language you want to support. The original file contains the keys and the English translations for them. For each language you want to support you can provide the translations in the localized version of the strings file.
Page 79 of 216
What You Need to Know for Your iOS App to Work Well With the SDK
Custom
implementation of
NSURLCache
To be able to present ads while offline, the SDK uses a custom implementation of the
system provided NSURLCache class. iOS allows setting only one shared cached application wide. For this reason, the shared cache the SDK puts in place at initialization
time might get called for requests that relate to your own application.
Important: ADTECH Mobile SDK does not stop, save, store, log, change or in any way
manipulate the requests it intercepts due to the shared cache put in place. The shared
cache serves only for displaying pre-downloaded resources for offline ads. It transparently forwards to the OS any requests that do not relate to these offline enabled ads.
If you are uncomfortable with SDK possibly getting called for your own requests, you
can disable the SDK’s caching mechanism with the following code place somewhere in
your app after the application gets started.
NSUInteger memoryCapacity = [NSURLCache sharedURLCache].memoryCapacity;
NSUInteger diskCapacity = [NSURLCache sharedURLCache].diskCapacity;
NSURLCache *defaultCache = [[NSURLCache alloc] initWithMemoryCapacity:memoryCapacity
diskCapacity:diskCapacity diskPath:nil];
[NSURLCache setSharedURLCache:defaultCache];
[defaultCache release]; // for non-ARC code
Note: Doing this will cause the SDK to not show offline ads properly. Do not book
cache-able ads if you are disabling the SDK’s shared cache.
If you want to use in your application a custom implementation of URL caching, you
should ensure that you forward the calls that you do not handle to the previously set
cache, i.e. chaining of caches.
If you do not set your own caching then you do not have to do anything in order for
the SDK to work well with your application.
The SDK’s custom cache implementation might come in conflict with your own caching
if not properly forwarded the calls for cached responses. When you set your custom
caching handler, please keep a reference in your code to the previously set shared
cache and forward it the calls you get from the system and that you do not handle
yourself. The code snippets below exemplify how to do this.
Keep a reference to
the previously set
shared cache
- (void)initMyCache
{
// previously set shared cache, keep this reference and make it reachable from your URLCache
subclass
NSURLCache *chainedCache = [NSURLCache sharedURLCache];
// create your own cache
myURLCache = [[MyURLCache alloc] init];
// make your app use your cache
[NSURLCache setSharedURLCache:myURLCache];
}
2012-12-18
Page 80 of 216
MyURLCache class
snippet
- (NSCachedURLResponse *)cachedResponseForRequest:(NSURLRequest *)request
{
// your code
if (!requestHandledByYourCode)
{
return [chainedCache cachedResponseForRequest:request];
}
}
- (void)removeCachedResponseForRequest:(NSURLRequest *)request
{
// your code
if (!requestHandledByYourCode)
{
[chainedCache removeCachedResponseForRequest:request];
}
}
UI misalignment on
exiting fullscreen
video player after
device orientation
changes
Because of a bug in iOS, when using MPMoviePlayerController (or subclasses of
it, like ATMoviePlayerController) fullscreen in a navigation based application the
UI can become misaligned after doing device orientation changes and exiting the fullscreen mode. This is a known issue and it is acknowledged by Apple. You can find details about the issue on the official developer forum here
https://devforums.apple.com/message/587887#587887 (login needed) and on other
community sites, for example here
http://stackoverflow.com/questions/3089692/ipad-rotation-bug-when-using-mpmovie
playerviewcontroller.
There is a workaround provided for the issue which you can find in the post from the
official developer forum, but it has some visual side-effects, so you need to consider
carefully if you want to implement it in your application.
Direct linking to
internal applications
2012-12-18
When booking a click-url that should point to an internal app, such as the App Store or
iTunes, it is necessary to comply to the official Apple URL Scheme Reference. Only
these type of links are supported by the iOS Mobile SDK. See:
http://developer.apple.com/library/ios/#featuredarticles/iPhoneURLScheme_Referenc
e/Introduction/Introduction.html
Page 81 of 216
2.2.3
The Public Interface (iOS)
Introduction
This section describes the classes that the ADTECH Mobile SDK exposes and their public interface. It also lists the exposed protocols, enums and constants.
In this section
Topic
Page
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
2012-12-18
Page 82 of 216
iOS Class: ATBannerView
• Name: AITBannerView
• Inherits: UIView
About the class
Description:
Represents one ad banner that you can place in your app.
For each ad banner you want to place in your app create one instance of this class and
add it as a subview on one of the views visible on the screen.
If you implement the ATBannerViewDelegate protocol and set yourself as the delegate
of this object, it will call you back when different events occur in the ad’s lifecycle.
Properties
Property
Type
Directive
Since
Description
delegate
id<ATBannerView
Delegate>
assign
1.0
The delegate gets notified of different events in the
lifecycle of the ad.
Default: nil
Note: it is not required to be set.
viewController
UIViewController
assign
1.0
The view controller that is the presenter of the ad view
being shown.
Default: nil
Important:
• You must set this property before calling load. Ads
will not get loaded without this property being set.
• This view controller should be able to presenting
modally other view controllers. It should be part of
the view controller stack of your application.
configuration
ATAdConfiguration readonly
1.0
Allows configuring the ad and specifying different parameters for better targeting. Although the configuration object is read-only, the properties that exposes are
read/write and can be modified at runtime to better
suite the apps needs.
Default: set on ATBannerView initialization using the
values found in the ADTECHAdConfiguration.plist file.
2012-12-18
Page 83 of 216
Property
Type
Directive
Since
Description
visible
BOOL
readwrite
1.0
Set the value to reflect the visibility of the banner on
screen (e.g. when the banner goes off screen set this to
NO and when it comes back into view set it to YES).
Default: YES
Note: While the banner’s visibility is NO, its activity is
paused and no new ads are fetched.
Important: You should always set the visibility of the
banner when its state of being shown changes. Different scenarios for when the banner is not visible could
include one of the following:
• A different screen is being shown, not the one
containing the banner.
• The ad exits the screen being placed on a scrollable
view (table view, scroll view).
• Another view temporarily overlays the banner and
blocks its visibility to the user.
A suggestion for managing the ad visibility is setting the
value inside the viewDidAppear and viewDidDisappear methods of your view controllers. For details see Setting the visibility flag of the banner in How
to Add a Banner Using Interface Builder (iOS) on page
64.
Instance messages
Instance Message
Return
Parameters
Since
Description
load
void
none
1.0
Begins loading the ads.
Note: The delegate will be called on events only after
this call.
Important:
• The ad should be configured before calling this
method.
• Before calling load you should always check the
validity of the ad configuration by checking the
configuration isValid property. Failing to ensure a
valid configuration will result in the ads not being
correctly loaded and displayed.
2012-12-18
Page 84 of 216
iOS Class: ATInterstitialView
• Name: ATInterstitialView
About the class
• Inherits: NSObject
Description:
Represents one interstitial ad view that you place in your app at various times and
places.
For each interstitial ad you want to display, create one instance of this class.
If you implement the ATInterstitialViewDelegate protocol and set yourself as
the delegate of this object, it will call you back when different events occur in the ad’s
lifecycle.
Properties
Property
Type
Directive
Since
Description
delegate
id<ATBannerView
Delegate>
assign
1.0
The delegate gets notified of different events in the
lifecycle of the interstitial view.
Default: nil
Note: It is not required to be set.
viewController
UIViewController
assign
1.0
The view controller that is the owner of the interstitial
view being shown.
Default: nil
Important:
• You must set this property before calling load. Ads
configuration
ATAdConfiguration readonly
1.0
Allows configuring the ad and specifying different parameters for better targeting. Although the configuration object is readonly, the properties that exposes are
read/write and can be modified at runtime to better
suite the apps needs.
Default: Set on ATInterstitialView initialization using the values found in the ADTECHAdConfiguration.plist file.
isReady
2012-12-18
BOOL
readonly
2.0
Returns YES when an interstitial ad is ready to be presented. You should call present only after isReady is
YES. The value changes to YES when the delegate is notified of a new ad being available and changes to NO
when present is called on the interstitial and it gets
presented.
Page 85 of 216
Instance messages
Instance Message
Return
Parameters
Since
Description
load
void
none
1.0
Begins loading the interstitial ad.
Note: The delegate will be called on events only after
this call.
Important:
• The ad should be configured before calling this
method.
• Before calling load you should always check the
validity of the ad configuration by checking the
configuration isValid property. Failing to ensure
a valid configuration will result in the ads not being
correctly loaded.
present
2012-12-18
void
none
2.0
Call this method after the interstitial is successfully
loaded to present it modally on screen. The presenter
view controller is the one that must have been set on
the banner or interstitial view.
Page 86 of 216
iOS Class: ATMoviePlayerController
• Name: ATInterstitialView
About the class
• Inherits: MPMoviePlayerController
Description:
Movie player that allows for VAST compliant advertisement. Depending on the configuration provided ads will be fetched and presented during the playback of the video
content.
Currently, linear videos are supported (pre-roll, mid-roll and post-roll video ads).
The ATMoviePlayerController can be used as a normal movie player controller that will
introduce ads during playback of the video content as configured.
Important: You must call stop before releasing the movie player on iOS 4.3 or earlier.
Properties
Property
Type
Access
Since
Description
configuration
ATVideoAdConfiguration
retain
2.2
The configuration specifies the placement details used
for serving ads and the type of ads to be presented.
presentingViewController
UIViewController
assign
2.2
The view controller that is the presenter of the video
being shown. It is used to present modally screens
when the user engages and interacts with the shown
ads.
Important:
• You must set this property before calling play. Ads
2012-12-18
Page 87 of 216
iOS Class: ATBaseConfiguration
• Name: ATBaseConfiguration
About the class
• Since: 2.2 (for exceptions see below in this topic)
Description:
Holds the generic configuration for ADTECH services.
Default values are loaded into memory from the ADTECHAdConfiguration.plist when
the configuration object is initialized. You can change the values in the configuration
object anytime at runtime.
Properties
Property
Type
Access
Since
Description
hostApplicationName
NSString
readonly
1.0
Holds the name of the current app where the ADTECH
Mobile SDK is integrated and used.
Note: The property is readonly and its value is loaded
from the ADTECHAdConfiguration.plist when on
creation. You need to manually ad the name of the
host app into the ADTECHAdConfiguration.plist
property file.
Important: In case that different campaigns are needed
for different versions of the same app you can customize this name by building in the app version as well (e.g.
“MyHostApplication_v1.0” or “MyHostApplication1.0”). You need to make sure the campaigns targeting this separate versions also have the same description for the targeted application.
networkID
NSUInteger
readwrite
1.0
Holds the network id of the ad provider. This is configured on the Adtech IQ server.
Default: Will be loaded from the ADTECHAdConfiguration.plist property file upon creation.
subNetworkID
NSUInteger
readwrite
1.0
Holds the sub network id of the ad provider. This is
configured on the ADTECH IQ server.
animation
ATAnimation
readwrite
1.0
Holds the default animation for changing consecutive
ads on an ATBannerView.
alias
NSString
copy
1.0
The alias uniquely identifies an ATBannerView or
ATInterstitialView within the app and it represents the placement of the ad within an app.
Default: nil
Note: There is no validation performed on alias outside
checking for nil and empty string (e.g. "").
2012-12-18
Page 88 of 216
Property
Type
Access
Since
Description
openLandingPagesThro
ughBrowser
BOOL
assign
3.0.1
Controls the behavior when opening landing pages for
non-rich type ads.
• When the value is set to YES, all landing page
URLs will open in the in-app browser. Use this
value when you know that all your landing page
URLs are pointing to web pages.
• When the value is set to NO, the landing page
URL will be processed before opening it to determine its type. If it is determined that it points
to a web page, the in-app browser is shown and
the page is loaded. If it is determined that the
landing page URL is a platform specific URL requesting access to native features (like using the
"tel:" protocol for making phone calls), that action is taken without showing the in-app browser. Making phone calls will prompt the users for
permission.
All the platform supported URL schemes are permitted.
You can find details about what these are here:
http://developer.apple.com/library/ios/#featuredarticl
es/iPhoneURLScheme_Reference/Introduction/Introdu
ction.html
Default values will be loaded from the ADTECHAdConfiguration.plist property file upon creation. If the value
is missing from the configuration file, defaults to YES.
Note: Setting the value to NO will cause slight delays in
taking the action or showing the landing web page,
because of the time the SDK needs to process the URL.
If the value is YES and a platform specific URL is set as
the landing page URL the in-app browser is shown
which will then handle on its own the special scheme.
This can leave a blank in-app browser shown when returning to the application.
2012-12-18
Page 89 of 216
Instance methods
Instance Method
Return
Parameters
Since
Description
isValidDomain
BOOL
aDomain:NSString
1.0
Checks if the string passed as parameter corresponds to the SDK’s valid domain template.
isValidAlias
BOOL
anAlias:NSString
1.0
Checks if the string passed as parameter corresponds to the SDK’s valid alias template.
addUserKey:values:e
rror
BOOL
key:NSString
1.0
Enables the developer to add custom key value
parameters that should be passed to the server
when requesting an ad.
values:NSArray
error:NSError
Return: YES if the operation was successful, NO
otherwise. If NO is returned the developer can
check the error parameter passed for a better
refining of the error that occurred.
Important:
• There are restrictions that apply for keys
and values added. Anything that exceeds
this limitation will be ignored with a warning log and an error will be generated.
• The maximum number of key value pairs
that can be used on one ad is 26. If you try
to add more key values, a warning is logged
and an error generated.
• As a general consideration, this key value
pairs will be used for creating the ad request URL that has a length limitation of
4096. It might be that although the above
constraints are kept, still the URL to be too
long (e.g. adding one key value pair, where
the value is an array with 128 tokens each
with 48 chars). This will be ignored at URL
construction and you will get a warning.
order might be different from that of the
input array.
allUserKeys
NSArray
none
1.0
Returns all the user defined keys from the configuration. Returns empty is no key is found.
valuesForKey
NSArray
sKey:NSString
1.0
Returns all the values for a given key. Returns nil
is the key was not found.
removeValues:forKey:error
BOOL
values:NSArray
1.0
Enables the user to remove a given value for a
given key. Useful when the key contains multiple
values (e.g. country = UK, DE, USA, FR) and only
one needs to be removed (e.g. USA).
key:NSString
error:NSError
Note: If the key is nil or not found then the call
is ignored.
Return: YES if the operation was successful, NO
otherwise. If NO is returned the developer can
check the error parameter passed for a better
refining of the error that occurred.
2012-12-18
Page 90 of 216
Instance Method
Return
Parameters
Since
Description
removeUserKey
void
key:NSString
1.0
Removes the values for the specified key. If key
is not found the call is ignored.
removeAllUserKeys
void
none
1.0
Removes all the key value pairs.
Class Message
Return
Parameters
Since
Description
setLoggingLevel
void
level:ATLoglevel
1.0
Sets the logging level for the ADTECH Mobile
SDK.
Class messages
Possible values: kATLogOff, kATLogError, kATLogWarning, kATLogInfo, kATLogVerbose
Default: kATLogOff
version
2012-12-18
NSString
none
2.2
Returns the current version of the SDK in use.
Page 91 of 216
iOS Class: ATAdConfiguration
• Name: ATAdConfiguration
About the class
• Inherits: ATBaseConfiguration
Description:
Holds the configuration of an ad. You can set here different parameters for controlling
the ad’s behavior and for better user targeting.
Default values are loaded into memory from the ADTECHAdConfiguration.plist
when the configuration object is initialized. You can change the values in the configuration object anytime at runtime.
Properties
Property
Type
Directive
Since
Description
animation
ATAnimation
readwrite
1.0
Holds the default animation for changing consecutive
ads on an ATBannerView.
refreshInterval
NSUInteger
readwrite
1.0
Holds the default refreshInterval for the ads displayed
on the ATBannerView.
Note: In case the ad internally specifies its own refreshInterval, that refreshInterval will overrule this default one set by you.
Important:
• The refresh interval needs to be between values
kATRefreshMin and kATRefreshMax. Exception
to this rule is the kATRefreshNever.
• If the refresh interval is lower than kATRefreshMin, then it will be reset by the SDK to kATRefreshMin.
• If the refresh interval is higher than kATRe-
freshMax, then it will be reset by the SDK to
kATRefreshMax.
groupID
NSUInteger
readwrite
1.0
Holds the group id of the ATBannerView. This is used
to solve tilling and companion situations where two or
more banners should show ads relative to each other.
Default: 0
2012-12-18
Page 92 of 216
Property
Type
Directive
Since
Description
enableImageBannerR
esize
BOOL
readwrite
2.2.1
Allows or disallows banner auto-resizing to the actual
image size received for simple image ads.
For example, when enabled, if a banner is set to have
the initial size of {320, 50} and a simple image ad is received of size {240, 40}, the banner will resize itself to
{240, 40}. If the next ad is {320, 50}, the banner resizes
itself again to {320, 50}.
When enabled, the banner adapts its size to the actual
size of the simple image ad received. Mediated ads do
not trigger re-sizing.
When the banner is about to resize it will call the [ATBannerViewDelegate willResizeAd:toSize:] on its delegate.
After the banner has resized it will call the [ATBannerViewDelegate didResizeAd:toSize:] on its delegate.
Note: The minimum accepted size is {3, 3}, smaller sizes like {1, 1} and {2, 2} will considered as tracking pixels.
Default: NO
isValid
BOOL
readonly
1.0
By checking this property you can see if the configuration is valid or not according to the constraints found
on different configuration properties.
maxSize
CGSize
readwrite
2.0
(deprecated)
Sets the maximum size an ad can resize to.
2.0
Allows or disallows usage of location services for
ADTECH ads.
allowLocationServices
BOOL
readwrite
Note: Starting 3.0 this property is deprecated and will
be ignored.
Important: If you want ADTECH ads to use your location for richer ads, you need to explicitly allow the SDK
to use the Location Services. By default the SDK is not
allowed to use them. You can enable location services
per app, through the configuration file or per ad
placement using this flag in the configuration.
isiAdEnabled
BOOL
readonly
2.0
Shows if iAd support is enabled or not. To be enabled,
the iOS version must support iAd (4.0 or greater on
iPhone and 4.2 or greater on iPad) and the configuration file must contain an iAdConfig entry. This entry is
set by the user when it wants to enable iAd.
adMobConfig
ATAdMobConfiguration
readonly
2.0
The AdMob specific configuration parameters. Only
used when AdMob SDK is installed.
millennialConfig
ATMillennialConfiguration
readonly
2.0
The Millennial specific configuration parameters. Only
used when Millennial SDK is installed.
greystripeConfig
ATGreystripeConfiguration
readonly
2.0
The Greystripe specific configuration parameters. Only
used when Greystripe SDK is installed.
vdopiaConfig
ATVdopiaConfiguration
readonly
2.0
The Vdopia specific configuration parameters. Only
used when Vdopia SDK is installed.
2012-12-18
Page 93 of 216
iOS Class: ATVideoAdConfiguration
• Name: ATVideoAdConfiguration
About the class
• Inherits: ATBaseConfiguration
Description:
Holds the configuration for video ads shown by ATMoviePlayerController.
You create an instance of this object and set on it the needed values in order to receive and show video ads from a placement you have configured server side.
Set the configuration object on the ATMoviePlayerController that you use, once it is
configured.
If you change the configuration while already playing video content, the changes will
take effect only when fetching new ads.
Properties
Property
Type
Access
Since
Description
videoDimension
CGSize
assign
2.2
The optional desired size for the video ads. If set, a
video of exact size is requested.
Defaults to CGSizeZero.
videoLength
NSTimeInterval
assign
2.2
The optional desired video ad length. If set, matching
video length will be smaller or equal to the specified
value.
Defaults to 0.
videoBitrate
NSUInteger
assign
2.2
The optional video ad bitrate in kbps. If set, only a video of exactly the same bitrate can match.
overlays
NSArray
readonly
2.2
The array of configured overlays to show during content playback.
maxWrapperRedirections
NSUInteger
assign
2.2
The maximum number of times wrapper redirections
will be followed until reaching an actual inline video ad.
For an understanding of what a wrapper is, please
consult the IAB VAST documentation.
The default value is 3. If you don't know and do not
care about this value then leave it unchanged.
isValid
BOOL
none
2.2
By checking this property you can see if the configuration is valid or not. For validity the following properties
are checked: hostApplicationName, domain, placementID
E.g. You can use this property to make sure that the
configuration is correctly set up before playing the ATMoviePlayerController object.
2012-12-18
Page 94 of 216
Instance methods
Instance Method
Return
Parameters
Since
Description
enableAdType
void
type:ATVideoAdTy
pe
2.2
Enables presentation of the video ad type specified as parameter, if not already enabled.
Possible values are: kATVideoAdPreRoll, kATVideoAdMidRoll and kATVideoAdPostRoll.
disableAdType
void
type:ATVideoAdTy
pe
2.2
Disables presentation of the video ad type specified as parameter, if it was enabled.
isAdTypeEnabled
BOOL
type:ATVideoAdTy
pe
2.2
Checks if presentation of the video ad type
specified as parameter is enabled or not.
addOverlay
void
overlay:ATVideoAdOve
rlay
2.2
Adds a new overlay to be shown during content
playback.
removeOverlay
void
overlay:ATVideoAdOve
rlay
2.2
Removes an overlay from the array of overlays
to be shown during playback.
2012-12-18
Page 95 of 216
iOS Class: ATVideoAdOverlay
• Name: ATVideoAdOverlay
About the class
Description:
Defines the configuration for one overlay (non-linear) ad to be shown during content
playback. For each overlay you want shown during content playback, you create an
instance of this class, configure it and add it to the ATMoviePlayerController configuration.
Properties
Property
Type
Access
Since
Description
startTime
NSTimeInterval
assign
2.2
The number of seconds of content playback to show
the overlay after.
The period of time during which the content is paused
or scrubbed through will be subtracted and won't
count towards showing the overlay.
i.e. Only actual playback of content is tracked and can
trigger the appearance of the overlay.
duration
NSTimeInterval
assign
2.2
Time interval the overlay should be displayed for, in
seconds.
placement
ATVideoAdOverlayPlacement
assign
2.2
The region of the video player view to show the overlay
on.
Possible values are: kATOverlayPlacementBottom, kATOverlayPlacementTop, kATOverlayPlacementLeft, kATOverlayPlacementRight.
The default value is kATOverlayPlacementBottom.
percentOfMargin
NSInteger
assign
2.2
The percent of margin to allow from the selected edge
through the placement.
The value must in the range 0 to 100.
e.g. Setting a value of 10 with the placement value
kATOverlayPlacementBottom will place the overlay at
10% of the video player height from the bottom edge.
The set value is normalized to be in the allowed range.
The default value is 0.
2012-12-18
Page 96 of 216
Property
Type
Access
Since
Description
secondsUntilDismissable
NSInteger
assign
2.2
The number of seconds to wait from the moment the
overlay is shown until it is allowed being dismissed.
If you want the overlay to be dismissable from the
start, use the kATOverlayDismissAllowedFromBeginning constant.
If you want the overlay to never be dismissable (for the
duration of it being shown), use the kATOverlayDismissNotAllowed constant.
If you set a value greater or equal to the duration, it
will count as kATOverlayDismissNotAllowed.
If the default value (kATOverlayDissmisDefault) is left in
place, the overlay will be dismissable after half of the
duration.
Instance methods
Instance Method
Return
Parameters
overlayWithStartTime:andDuration
ATVideoAdOverlay startTime:NSTimeInter
val
Since
Description
2.2
Convenience method to create an overlay with
startTime and duration.
duration:NSTimeInterv
al
2012-12-18
Page 97 of 216
iOS Protocol: ATBannerViewDelegate
• Name: ATBannerViewDelegate
About the protocol
Description:
Protocol used by the ATBannerView to communicate with its delegate.
Implement this protocol to be notified of different events in the lifecycle of a banner
view.
Callbacks
Message
Type
Return
shouldSuspendForAd
optional void
Parameters
Since
Description
view:ATBannerVie
w
1.0
Called when the ad will take over the screen in
order to give the app the chance to pause ongoing activities. This is in response for user interaction with the ad.
Parameter: The banner view that will take over
the screen.
shouldResumeForAd
optional void
view:ATBannerVie
w
1.0
Called when the ad will relinquish control of the
screen as a result of the user dismissing it.
Parameter: The banner view that had control of
the screen.
willLeaveApplicationForAd
optional void
view:ATBannerVie
w
1.0
Called when the user interaction with the ad
triggers leaving the app. This can be, for example, opening a URL in Safari or Maps or another
app registered to handle the URL specified by
the ad.
Note: you should save the state of the app when
you get this call.
Parameter: The banner view that triggered
leaving the app.
didFetchNextAd
optional void
view:ATBannerVie
w
1.0
Called when an ad is successfully fetched from
the configured campaign. You will get one call
each time a new ad is fetched successfully from
the campaign.
Parameter: The banner view that displays ad.
didFetchDefaultAd optional void
view:ATBannerVie
w
1.0
Called when an ad could not be fetched from a
campaign, but a default one was provided. You
will get one call each time a default ad it
fetched.
Parameter: The banner view that displays the
ad.
2012-12-18
Page 98 of 216
Message
Type
Return
didFailFetchingAd
optional void
Parameters
Since
Description
view:ATBannerVie
w
1.0
Called when an ad could not be fetched with the
currently set configuration. You will get one call
each time an ad failed being fetched. If the configuration allows auto-refresh, a new ad is requested automatically.
Parameter: The banner view that displays the
ads.
willResizeAd:toSize:
optional void
view:ATBannerVie
w
1.0
size:CGSize
Called when the ad is about to resize. You could
at this time rearrange your application content
to make space for the resized ad.
If you want to animate the ad being resized this
a good place to do it. An ad can both grow or
shrink as a result of a resize.
Not all ads will exercise the option of resizing.
Resizing ads should be placed on screens where
the application content allows rearranging or
can accommodate a resized ad.
Even if the content is not resizing, the ad will
still try to resize over the application content
(until closed).
Note: The ad frame will be changed automatically according to the resize parameters received from the ad. The SDK will try to place the
ad at the highest possible Z order within only its
direct parent view in order to cover the application content. After the ad closes, its initial frame
will be restored.
Parameters:
• view: The ad view that is going to be resized
• size: The size the ad is going to be resized to
didResizeAd:toSize optional void
:
view:ATBannerVie
w
size:CGSize
1.0
Called when the ad finished resizing to the specified size.
Parameters:
• view: The ad view that was resized
• size: The size the ad was resized to
2012-12-18
Page 99 of 216
iOS Protocol: ATInterstitialViewDelegate
• Name: ATInterstitialViewDelegate
About the protocol
Description:
Protocol used by the ATInterstitialView to communicate with its delegate.
Implement this protocol to be notified of different events in the lifecycle of the interstitial view.
Callbacks
Message
Type
Return
Parameters
Since
Description
didHideInterstitialAd
required
void
view:ATInterstitial
View
1.0
Called either when the ad is dismissed by the
user or the refresh timer fires for the ad.
Note: The interstitial was dismissed by the time
you get this call. This when you need to make
sure that the user sees your application’s content on screen.
Parameter: The interstitial view that is shown.
didSuccessfullyFetchInterstitialAd
optional void
view:ATInterstitial
View
1.0
Called when the interstitial ad is fetched from a
campaign and available to be displayed.
Note: You should put up the ad on the screen at
this timer.
Parameter: The interstitial view that is shown.
didFetchDefaultInterstitialAd
optional void
view:ATInterstitial
View
1.0
Called when a default interstitial ad was fetched
instead of an ad from a campaign. Should this
suffice, you can put the ad on the screen at this
time. If a default ad is not desired, you can call
load again and wait for another ad.
Note: You can make changes to the configuration before calling load again.
Parameter: The interstitial view that fetched the
ad.
didFailFetchingInterstitialAd
optional void
view:ATInterstitial
View
1.0
Called when an ad fails to be fetched. Usually
this happens because of networking conditions
and in rare cases if an exception occurs on the
server.
Note: You can call load to try again, if you think
the conditions leading to the error have
changed.
Parameter: The interstitial view that failed getting an ad.
2012-12-18
Page 100 of 216
Message
Type
Return
willLeaveApplicationForInterstitialAd
optional void
Parameters
Since
Description
view:ATInterstitial
View
1.0
Called when the user interaction with the ad
triggers leaving the app. This can be, for example, opening a URL in Safari or Maps or another
app registered to handle the URL specified by
the ad.
Note: You should save the state of the app when
you get this call.
Parameter: The ad view that triggered leaving
the app.
2012-12-18
Page 101 of 216
iOS Enums
ATAnimation
Description: Types of animations that can be used to animate transition from one ad
to the other.
Since: 1.0
Values:
ATLogLevel
Value
Description
ANIMATION_NONE
No animation when changing ads.
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.
TOP_TO_BOTTOM
The new ad will transition by pushing the old one out of the way vertically from a top down direction.
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.
UNDEFINED
Undefined animation, when the SDK encounters these, it will use the
default one, see iOS Constants on page 104.
Description: The log levels that can be for the ADTECH Mobile SDK library.
Since: 1.0
Values:
ATGender
Value
Description
kATLogOff
No logging.
kATLogError
Only errors will be logged.
kATLogWarning
Errors and warnings will be logged.
kATLogInfo
Errors, warnings and general information will be logged.
kATLogVerbose
Detailed logging.
Since: 2.0
Description: The gender used to provide more relevant ads to the user of your application.
Values: kATGenderUnknown, kATGenderMale, kATGenderFemale
ATVideoAdType
Since: 2.2
Description: The available ad type to be presented during playback of video content.
Values: kATVideoAdPreRoll, kATVideoAdMidRoll and kATVideoAdPostRoll
2012-12-18
Page 102 of 216
ATVideoAdOverlayPl
acement
Since: 2.2
Description: The available placements for an overlay.
Values: kATOverlayPlacementBottom, kATOverlayPlacementTop, kATOverlayPlacementLeft, kATOverlayPlacementRight
ATVideoAdOverlayDi
smissTime
Since: 2.2
Description: The special values assignable to the secondsUntilDismissable property of
ATVideoAdOverlay.
Values: kATOverlayDismissDefault, kATOverlayDismissNotAllowed, kATOverlayDismissAllowedFromBeginning
2012-12-18
Page 103 of 216
iOS Constants
Constants in the
animation area
Constants in the
configuration area
Constants in the
refresh area
2012-12-18
Since: 1.0
Constant
Type
Description
kATDefaultAnimation
ATAnimation
The default fallback animation.
Since: 1.0
Constant
Type
Description
kATConfigErrorDomain
NSString
The error domain that the SDK will return
when some error happens on the ATAdConfiguration.
kATConfigErrorCode
int
The error code that the SDK will return when
some error happens on the ATAdConfiguration.
kATConfigEmptyKeyError
int
The error code passed when the key is empty.
kATConfigNilKeyError
int
The error code passed when the key is nil.
kATConfigKeyNotFoundError
int
The error code passed when the key is not
found.
kATConfigEmptyValuesError
int
The error code passed when the values
passed are empty.
kATConfigInvalidCharError
int
The error code passed when an invalid char
is used.
kATConfigValueNotStringError
int
The error code passed when the value is not
string.
kATConfigMaxLengthExcededError
int
The error code passed when the max allowed length is exceeded.
kATConfigMaxKVPairsExcededError
int
The error code passed when the max allowed count for key value pairs is exceeded.
kATConfigMaxValueTokensPerKeyExcededError
int
The error code passed when the max allowed tokens count per one key is exceeded.
Since: 1.0
Constant
Type
Description
kATRefreshMin
NSUInteger
The minimum refresh interval that can be set in
the ATAdConfiguration.
kATRefreshMax
NSUInteger
The maximum refresh interval that can be set in
the ATAdConfiguration.
kATRefreshNever
NSUInteger
The value that means that an ad should never
be refreshed in an ATBannerView.
kATRefreshDefault
NSUInteger
The default fallback refresh interval.
Page 104 of 216
2.2.4
In this section
How to Use Mediation for Third Party Advertisement SDKs
in iOS
Topic
Page
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
2012-12-18
Page 105 of 216
How to Add a Third Party SDK (iOS)
Add a 3rd party SDK to
be used by ADTECH
Mobile SDK
Step
Action
1
Download the SDK from the provider’s website.
2
Follow the instructions that are provided from the SDK to add the SDK to the project.
The ADTECH Mobile SDK will automatically detect that a supported 3rd party SDK is
available and will try to use it.
3
Configure the installed 3rd party SDK. You can choose from the following options:
• Use the configuration file provided for setting default values (ADTECHAdConfiguration.plist)
• Use the specific configuration objects inside ATAdConfiguration.
Each supported SDK will have a corresponding configuration object in ATAdConfiguration. Use this configuration to set up the needed information for using the
3rd party SDK. In case you do not want to use a 3rd party SDK, remove its configuration from the ADTECHAdConfiguration.plist file or set its corresponding configuration object from ATAdConfiguration to nil. When the ADTECH Mobile SDK checks
the availability of any 3rd party SDK it expects the following conditions to be met:
• The specific public classes exposed by the 3rd party SDK are available to be
instantiated, and
• the configuration object from ATAdConfiguration corresponding to the 3rd
party SDK is not nil.
2012-12-18
Page 106 of 216
Supported Third Party SDK’s (iOS)
Supported 3rd Party
SDK’s
The ADTECH Mobile SDK supports the following 3rd party SDK’s for mediation:
3rd Party
SDK
Version
ATAdConfiguration ivar
ADTECHAdConfiguration.plist
entry
Download link
AdMob
5.0.8
adMobConfig
AdMobConfig
https://developers.goo
gle.com/mobile-ads-sd
k/download#downloadi
os
Millennial
Media
4.5.3
millennialConfig
MillennialConfig
http://developer.millen
nialmedia.com
Use the static library that integrates the SBJSON lib.
isiAdEnabled
iAdConfig
(included in the iOS
SDK 4.0 and later)
Banners are available on
iPhones and iPods starting
with iOS 4.0 and on iPads
starting with iOS 4.2.
iAds
Notes
Interstitials are available only
on iPads starting with iOS 4.3.
Greystripe
3.1.3
greystripeConfig
GreystripeConfig
https://developer.greys
tripe.com/sdks (login
needed)
Vdopia
4.1.0
vdopiaConfig
VdopiaConfig
http://wiki.ivdopia.com Banner ads and in-app ads are
/file-cabinet
supported. There is no support
for pre-apps.
Interstitials are not supported.
Interstitials (in-apps) are
shown until the user dismisses
then. i.e. They will not get automatically dismissed.
2012-12-18
Page 107 of 216
AdMob Configuration in the ADTECH Mobile SDK (iOS)
ADTECHAdConfigurat
ion.plist file
configuration
Banner/interstitial
configuration
The default configuration of AdMob should be placed in the ADTECHAdConfiguration.plist file, under the AdMobConfig section. Here you can set the following parameters:
Parameter
Description
AdUnitID
Your AdMob unit identifier. This is a mandatory parameter on any
banner or interstitial served by AdMob.
Keywords
An array of keywords used to serve more relevant ads.
Gender
The gender of the application user (if can be determined).
TestDevice
The UDIDs of the devices used for testing. By setting this value you
make sure your test devices will not make false impressions. Additionally, there is always an ad available for testing purposes.
AdditionalParameters
A dictionary of key value pairs that are passed unaltered to the
AdMob SDK.
Each banner or interstitial view can be configured on its own. If no such configuration
is provided, the default values from the configuration file are used. From code, by setting members of the ATAdMobConfiguration object (part of ATAdConfiguration), you
can additionally customize the following parameters:
• birthday
• location
• locationDescription
For details about the meaning and usage of these parameters please see AdMob’s
page for targeting:
http://code.google.com/mobile/ads/docs/ios/intermediate.html#targeting
2012-12-18
Page 108 of 216
iAd Configuration in the ADTECH Mobile SDK (iOS)
Configuration of iAd
3rd party SDK
iAd is configured using the Apple iTunes Connect portal on a per application basis. You
must enable iAd for your application using this portal, otherwise you will not get iAd
ads. Once iAd is enabled, you get tests ads in your application until your app gets approved on the AppStore, then you start getting live ads.
To allow the ADTECH Mobile SDK to work with iAd:
Step
2012-12-18
Action
1
Add the iAd framework to your target.
2
Add an iAdConfig entry in the ADTECH configuration file. It does not need to
contain anything, just be present. Its role is to let the SDK know that iAd mediation is wanted.
Page 109 of 216
Millennial Configuration in the ADTECH Mobile SDK (iOS)
ADTECHAdConfigurat
ion.plist file
configuration
Banner/interstitial
configuration
The default configuration of Millennial Media should be placed in the ADTECHAdConfiguration.plist file, under the MillennialConfig section. Here you can set the following parameters:
Parameter
Description
GoalID
The Millennial Media Goal Id for tracking conversions for your application. This is optional, is left blank or missing then the conversions tracking will not be initialized.
AccelerometerEnabled
Use this method to enable or disable the accelerometer.
RequestData
Used to provide metadata that can help Millennial deliver more
relevant ads to your users. Metadata is information that your users
have shared with you, and you have permission to share with us
such as age, gender, zip code, income, and other such information.
For a list of possible keys see
http://wiki.millennialmedia.com/index.php/IOS_SDK.
RefreshTime
The internal timer duration for the rotation of Millennial ads in
seconds. Zero or negative value means never refres. We recommend setting a value of 0 for never refresh, this will ensure that the
Millennial internal timer does not overlap with the ADTECH Mobile
SDKs refresh timer. (The ADTECH Mobile SDK will allow a time-slot
when the Millennial Media banner is displayed and this banner will
also refresh internally if you do not set the RefreshTime to 0 or
negative)
Each banner or interstitial view can be configured on its own from code by setting
members of the ATMillennialConfiguration object (part of ATAdConfiguration). If no
such configuration is provided, the default values from the configuration file are used.
You need to individually configure for each placement the Millennial apid (unique per
placement). You can do this with the following line banner.configuration.millennialConfig.apid where banner is your ATBannerView placement.
If available, Millennial Media will use the users current GPS location for better targeting ads. By default this is not used (is nil) but you can set it any time during runtime
by using the static updateLocation: method from the ATMillennialConfiguration
class. This location will be used across Millennial Media on each placement from the
app. If you do not want to user location, make sure you set this to nil.
For details about the meaning and usage of these parameters please see Millennial
dev and wiki pages:
• http://wiki.millennialmedia.com/index.php/IOS_SDK.
• http://developer.millennialmedia.com
2012-12-18
Page 110 of 216
Greystripe Configuration in the ADTECH Mobile SDK (iOS)
ADTECHAdConfigurat
ion.plist file
configuration
The Greystripe SDK can be configured only through the ADTECHAdConfiguration.plist
file, under the GreystripeConfig section. Here you can set the following parameters:
Parameter
Description
appID
The application identifier you get from your Greystripe account.
This is NOT optional and you must provide a value for it in order for
Greystripe mediation to work.
adCountBySize
Greystripe needs to know in advance what type of ads and how
many of them you intend to use in your application.
This dictionary allows you to configure how many ad views (banners
and interstitials) do you want to use in your app for each ad size.
The available ad sizes are:
•
•
•
•
Banner (320x48)
iPadMediumRectangle (300x250)
iPadLeaderboard (728x90)
iPadWideSkyscrapper (160x600)
These are the keys in the adCountBySize dictionary and the value
for each of them is the number of distinct ad views that are needed
by the application. The SDK will not allow more Greystripe ad views
than configured. The configuration setting is optional. If not provided, it will default to a configuration having 1 banner ad view.
Important:
• Interstitials are not supported at this time.
• While developing your application, to see Greystripe ads, you need to register your
test devices on their site. Go to your Greystripe account and add as test devices
every device you want to see Greystripe provided ads on, including the simulator.
2012-12-18
Page 111 of 216
Vdopia Configuration in the ADTECH Mobile SDK (iOS)
ADTECHAdConfigurat
ion.plist file
configuration
The default Vdopia SDK configuration values can be set through the ADTECHAdConfiguration.plist file, under the VdopiaConfig section. You can set the following parameters:
Parameter
Description
appID
The application identifier you get from your Vdopia account. The
value is mandatory. If not set, Vdopia ads will not be served.
bannerLocation
This is the default position for banner showing Vdopia ads in your
application.
It can have only two values:
• 1: The banner is placed at the top of the screen.
• 2: The banner is at the bottom.
This value is not mandatory and can also be configured at runtime
for each banner view.
Note: Vdopia ads are allowed to use the users’ location only if the allowLocationServices value is set to YES in the ADTECH Ad configuration object.
2012-12-18
Page 112 of 216
2.3
ADTECH Mobile SDK: Android
In this chapter
Topic
Page
Getting Started with the ADTECH Mobile SDK for Android ................................ 114
How to Use the Mobile SDK in Android.............................................................. 121
The Public Interface (Android)............................................................................ 143
How to Use Mediation for Third Party Advertisement SDKs in Android ............ 146
2012-12-18
Page 113 of 216
2.3.1
In this section
Getting Started with the ADTECH Mobile SDK for Android
Topic
Page
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
2012-12-18
Page 114 of 216
How to Integrate the ADTECH Mobile SDK into Your Android App
Introduction
This topic serves as a guideline for application developers on how to integrate ADTECH
Mobile SDK into applications using the Android platform.
Prerequisite
To use the SDK for Android, Android version 2.1 or higher is required.
Content of the
ADTECHMobileSDK_
Android_2.2.4.zip
How to add the
ADTECHMobileSDK.ja
r into your Android
project with Eclipse
2012-12-18
Folder
Description
Docs
Contains the javadoc documentation of the public API.
Lib
Contains the ADTECHMobileSDK.jar.
Sample
Contains a sample application project which can be imported into Eclipse.
Step
Action
1
Create a new folder called libs in your project folder.
2
Copy the ADTECHMobileSDK.jar to the libs folder:
3
Add the jar to the build path of the project: Right click on ADTECHMobileSDK.jar,
select Build Path from the menu, then select Add to Build Path.
Page 115 of 216
How to update the
ADTECH Mobile SDK
to a newer version
If you are already using a version of the ADTECH Mobile SDK and a new one is released, we recommend that you update your application with the new version. New
releases introduce features, improvements and bug fixes based on your valuable input.
All the releases made so far are backwards compatible with the older versions, meaning that you do not have to change your code in order for it to work with the new version. If you do not want to use the newly introduced features that need coding, you
will not have to change anything in your application’s code. You will get however the
improvements and fixes.
To update:
Step
Action
1
Obtain the zip file with the new version of the ADTECH Mobile SDK.
2
Unpack the archive somewhere on your computer.
3
Remove from your project's lib directory the AdtechMobileSDK.jar file.
4
Add the new AdtechMobileSDK.jar file by following steps 2 and 3 from How to
add the ADTECHMobileSDK.jar into your Android project with Eclipse (see above).
That’s it! You should now be using the newer version of the ADTECH Mobile SDK.
2012-12-18
Page 116 of 216
Permissions for the Mobile SDK (Android)
About permissions
The ADTECH Mobile SDK requires a set of permissions declared in the AndroidManifest.xml file. Some of these permissions are required or optional, depending on
the configuration and requirements of the host application.
Permissions
Permission
Presence
Description
android.permission.INTERNET
Required
This permission is required because all the ads are downloaded over HTTP.
android.permission.ACCESS_NETWORK_STAT
E
Required
This permission is required because the ad container’s lifecycle depends on the state of the network. If the network is
stopped by the user the container’s downloading component
is paused and cached ads that have offline visibility are
showed to the user. Once the network is available again the ad
downloading component wakes up and starts downloading
new ads.
While offline and ads are loaded from the cache, events may
be triggered that influence monetization, so the container
needs to know when the network state changes to online so
that it can report these avents to ADTECH servers.
anRequired
droid.permission.WRITE_EXTERNAL_STORA
GE
This permission is required for caching offline enabled ads and
for device identification by ADTECH servers.
android.permission.READ_PHONE_STATE
This permission is required to obtain the device id value provided by the TelephonyManager API.
Optional
In some cases the Android device is not able to provide a
unique device id (i.e IMEI) which can be tracked by the
ADTECH servers, so the SDK generates a unique UUID that is
stored on the SD card (or external storage). The reason for
storing this information on the external storage is to enable
other applications that use the SDK to use the same device id
when connecting to ADTECH servers. This way ad targeting
can be much more precise not just across placements, but also across applications.
It is advised to use this permission to provide the best possible
data for ADTECH servers regarding ad statistics from a device.
If this permission is not provided the above mentioned UUID
generation will be used to create a device id, but that approach is less precise because the device id can be lost if the
SD card is formated and the application is reinstalled.
android.permission.ACCESS_FINE_LOCATION
Optional
This permission is required for rich media ads.
android.permission.SEND_SMS
Optional
android.permission.WRITE_CALENDAR
Optional
android.permission.READ_CALENDAR
Optional
android.permission.CALL_PHONE
Optional
2012-12-18
Page 117 of 216
Permission
Presence
Description
android.permission.GET_TASKS
Optional
This permission is required by 3rd party client side mediation
(i.e integrating the ADTECH SDK with admob, millennial,
vdopia, etc).
The SDK has a very specific internal state-machine and when
3rd party ads are used (i.e an Admob interstitial), the SDK
needs to know that the ad has been closed so that it may resume ad-fetching and report mediation-related events to
ADTECH. While a 3rd party interstitial/expanded ad is opened
in foreground the SDK pauses ad fetching to avoid false impressions. Since some of the 3rd party SDKs do not provide a
callback to notify the SDK that the ad has been closed, this has
to be checked dynamically. In order to do that the GET_TASKS
permission is required so that the SDK can read the activity
stack of its application.
Use cases for the
permissions
2012-12-18
Permission
Simple Image Ads
Client Side
Mediated Ads
(integration with
3rd party SDK’s)
Rich Media Ads
(ORMMA and
MRAID compliant ads)
INTERNET
Required
Required
Required
ACCESS_NETWORK_STATE
Required
Required
Required
WRITE_EXTERNAL_STORAGE
Required
Required
Required
READ_PHONE_STATE
Optional
Optional
Optional
ACCESS_FINE_LOCATION
Optional
Optional
Required
SEND_SMS
Optional
Optional
Required
WRITE_CALENDAR
Optional
Optional
Required
READ_CALENDAR
Optional
Optional
Required
CALL_PHONE
Optional
Optional
Required
GET_TASKS
Optional
Required
Required
Page 118 of 216
ADTECH Mobile SDK Release Notes and API Changelog (Android)
Release 3.0.1
New features
• Support for SDK handling of landing page URLs, instead of the web browser.
Maintenance
• Small bug fixes
Release 3.0
New features
• Support for MRAID2.0
Maintenance
• Device ID usage/generation
• AsyncTask fix
• Enable usage of direct landing page URIs
• Stability improvements and small bugfixes
API changelog
• BaseAdtechConfiguration: added methods setOpenLandingPagesThroughBrowser(boolean) and openLandingPagesThroughBrowserAllowed().
• AdConfiguration: the setMaxSize(LayoutParams maxSize) method has bee deprecated according to the MRAID2.0 specifications.
Release 2.2.4.1
Improvements
• Improved unique user identification
Release 2.2.4
Maintenance
• Fixed video not shown from MRAID interstitials
• Fixed VAST player not playing video when an empty VAST document is received
Release 2.2.3
New features
• Full support for ORMMA 1.0 and ORMMA 2.0 methods.
Maintenance
• Bug fix: Key values not sent for VAST requests
Release 2.2.1
New features
• Auto banner-resize
Maintenance
• Several bugs have been fixed
For the detailed changes in the API see the README.txt file in the .zip file.
2012-12-18
Page 119 of 216
Release 2.2
New features
• Support for VAST compliant video ads using the new public video player component
• Linear video ads (pre-, mid- and post-roll) are supported
• Non-linear video ads (image ad overlays) are supported. Image ads can be
shown during content playback as configured by the app developer
Maintenance
• Hide the ad media files (video, images) from the phone gallery
• Show a confirmation dialog while expanded ads try to access the geo-location services
• Remove the loading warnings when using the SDK on ICS
• Fixed banners start loading and showing ads when visibility is set to yes before
calling load
• Fixed CacheCleaner misbehavior, where expired ads where not deleted appropriately and valid ads where deleted instead
• Other small bug fixes
API changelog
• BaseAdtechConfiguration: Contains the basic adtech configuration information. (i.e
domain, alias, network).
• AdtechVideoView: Video player similar to the Android native VideoView which
provides an interface for VAST compliant ad serving.
• AdtechVideoVonfiguration: Configuration object for the requesting and behavior of
VAST ads.
• AdType: Enumeration of VAST compliant ad types.
• VideoViewListener: Listener for video view events registered by the AdtechVideoView.
• NonLinearConfiguration: Configuration object for the request and presentation of
Non Linear VAST specific ads.
Release 2.1
New features
• Support for 3rd party SDKs: AdMob, iAd, Millennial, Vdopia, GreyStripe
Improvements
• Allow the app-developer to control the ad’s viewable state
Maintenance
• Several memory leaks have been fixed
• minVersion could be set to values higher than 10
• SDK has been tested and optimized to work on Android 4.0+
2012-12-18
Page 120 of 216
2.3.2
In this section
How to Use the Mobile SDK in Android
Topic
Page
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
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
2012-12-18
Page 121 of 216
How to Add a Banner as a Resource (Android)
Introduction
This topic describes how to add an ADTECH banner as a resource. Alternatively, you
can add a banner dynamically. For details see How to Add a Banner Dynamically (Android) on page 125.
Note: To receive ads you are also required to provide the required configuration. For
details see How to Configure an Ad (Android) on page 132.
Procedure
Step
1
Action
Declare the AdtechBannerView in the layout XML:
<com.adtech.mobilesdk.view.AdtechBannerView
android:id="@+id/ad_container"
android:layout_width="300dip"
android:layout_height="50dip"
android:layout_alignParentBottom="true" >
</com.adtech.mobilesdk.view.AdtechBannerView>
2
Fetch the view from the XML in the Activity:
AdtechBannerView adtechView = (AdtechBannerView )
findViewById(R.id.ad_container);
3
Pass the ADTECH alias to the view:
adtechView.getAdConfiguration().setAlias("mycampaign-top-5");
4
Start the fetching of the ads:
@Override
protected void onResume() {
super.onResume();
Log.d(TAG, "onResume");
adtechView.load();
}
5
Stop the fetching of the ads:
@Override
protected void onPause() {
super.onPause();
Log.d(TAG, "onPause");
adtechView.stop();
}
2012-12-18
Page 122 of 216
Registering for
AdtechBannerView
events
To receive notifications regarding the life cycle and events of the AdtechBannerView
the app developer is required to implement the AdtechBannerViewCallback interface
and register it in the banner view via the setViewCallback(AdtechBannerViewCallback) method.
The following is an example implementation of the AdtechBannerViewCallback:
/**
* Optional: call-back for receiving notifications about the life-cycle of the ads.
*/
private AdtechBannerViewCallback adTechViewCallback = new AdtechBannerViewCallback() {
@Override
public void onAdSuspend() {
// This method is called to inform that the application should suspend its job, when the
advertisement has been
// resized and covers the whole screen. <p> This might be useful in applications like games,
or applications
// having video play-back.
Toast.makeText(getApplicationContext(), "The application should suspend its jobs.",
Toast.LENGTH_SHORT).show();
}
@Override
public void onAdSuccess() {
// This method is called when an ad was downloaded successfully.
Toast.makeText(getApplicationContext(), "Ad successfully displayed.",
}
@Override
public void onAdResume() {
// This method is called when the application has been resumed from the suspended state.
Toast.makeText(getApplicationContext(), "The application should resume its jobs.",
}
@Override
public void onAdLeave() {
// This method is called when the current application is left because the user clicked
a banner which will be
// opened in a the external browser.
Toast.makeText(getApplicationContext(), "Browser is opening.",
}
2012-12-18
Page 123 of 216
@Override
public void onAdFailure() {
// This method is called when an ad download failed. This could happen because of networking
reasons or other
// server communication reasons.
Toast.makeText(getApplicationContext(), "Ad download failed.",
}
@Override
public void onAdDefault() {
// This method is called when the default ad is loaded in the {@link AdtechBannerView}
container.
Toast.makeText(getApplicationContext(), "Default ad displayed.",
}
};
2012-12-18
Page 124 of 216
How to Add a Banner Dynamically (Android)
Introduction
This topic describes how to add an ADTECH banner dynamically. Alternatively, you can
add a banner as a resource. For details see How to Add a Banner as a Resource on
page 122.
Procedure
Step
1
Action
Create a new ad view and set its view configuration properties:
AdtechBannerView adtechView = new AdtechBannerView(getContext());
2
If the AdtechView is defined from code, layout parameters must be added:
LayoutParams params = new LayoutParams(LayoutParams.FILL_PARENT, 50);
adTechView.setLayoutParams(params);
3
4
@Override
super.onResume();
Log.d(TAG, "onResume");
adtechView.load();
}
5
Stop the fetching of the ads:
@Override
super.onPause();
Log.d(TAG, "onPause");
adtechView.stop();
}
2012-12-18
Page 125 of 216
How to Manage the Banner Life Cycle (Android)
Use appropriate life
cycle methods
ADTECH banner views consume a lot of resources and services while the application is
running so it is required to use the appropriate life cycle methods in your code to
avoid memory/service-leaks, battery and data consumption.
In the activity where the banner view is defined AdtechBannerView’s load() method
has to be called from onResume() and stop() has to be called from onPause().
Sample code
private AdtechBannerView banner;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// activity initialization
banner= new AdtechBannerView(this);
}
@Override
banner.load();
super.onResume();
}
@Override
banner.stop();
super.onPause();
}
2012-12-18
Page 126 of 216
How to Add an Interstitial (Android)
Introduction
This topic describes how to add an ADTECH Interstitial view to your application. The
steps are the same as in the cases described above in How to Add a Banner Dynamically on page 125 and How to Add a Banner as a Resource (Android) on page 122.
Procedure
Step
1
Action
Declare the AdtechInterstitialView in the layout XML:
<com.adtech.mobilesdk.view.AdtechInterstitialView
android:id="@+id/ad_interstitial"
android:layout_width="fill_parent"
android:layout_height="fill_parent" >
</com.adtech.mobilesdk.view.AdtechInterstitialView>
2
Fetch the view from the XML in the Activity:
AdtechInterstitialView interstitial = (AdtechInterstitialView )
findViewById(R.id.ad_interstitial);
3
interstitial.getAdConfiguration().setAlias("myinterstitial-top-5");
4
interstitial.load();
Alternatively, you can add a banner dynamically. For details see How to Add a Banner
Dynamically (Android) on page 125 and use AdtechInterstitialView instead of
AdtechBannerView.
Registering for
AdtechInterstitialVie
w events
To receive notifications regarding the life cycle and events of the AdtechInterstitialView the app developer is required to implement the AdtechInterstitialView
Callback interface and register it in the banner view via the setViewCallback(AdtechInterstitialView) method.
The following is an example implementation of the AdtechInterstitialViewCallback
interface:
private AdtechInterstitialViewCallback adtechInterstitialCallback = new
AdtechInterstitialViewCallback() {
@Override
public void onAdSuccess() {
// This method is called when an ad was downloaded successfully.
Toast.makeText(getApplicationContext(), "Interstitial ad successfully displayed.",
}
@Override
public void onAdDismiss() {
2012-12-18
Page 127 of 216
// This method is called when the expires and the interstitial view is dismissed.
Toast.makeText(getApplicationContext(), "Interstitial ad dismissed.",
}
@Override
public void onAdFailure() {
// This method is called when an ad download failed. This could happen because of networking
reasons or other
//server communication reasons.
Toast.makeText(getApplicationContext(), "Interstitial ad failed to display.",
}
@Override
public void onAdLeave() {
// This method is called when the application will be left because the user clicked on
an ad which is displayed in
// the external browser.
Toast.makeText(getApplicationContext(), "Browser is opening.",
}
@Override
public void onAdDefault() {
// This method is called when the default ad is loaded in the {@link AdtechBannerView}
container.
Toast.makeText(getApplicationContext(), "Default ad has been loaded.",
}
};
2012-12-18
Page 128 of 216
How to Manage the Interstitial Life Cyle (Android)
Use appropriate life
cycle methods
ADTECH interstitial views consume a lot of resources and services while the application is running so it is required to use the appropriate life cycle methods in your code
to avoid memory/service-leaks, battery and data consumption.
In the activity where the banner view is defined AdtechBannerView’s load() method
has to be called from onResume() and stop() has to be called from onPause().
Sample code
private AdtechInterstitialView interstitial;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// activity initialization
interstitial= new AdtechInterstitialView (this);
// rest of the interstitial's init
interstitial.load;
}
@Override
// don't call load
super.onResume();
}
@Override
interstitial.stop();
super.onPause();
}
2012-12-18
Page 129 of 216
Ad Container Restrictions (Android)
Exact sizes for the
containers
Due to the behavior of the rich media ads, which might load their content based on
the size of the container in which they are placed (this applies both for AdtechBannerView and AdtechInterstitialView) it is required that the developer provides
exact sizes for the containers. This means that for the width and height of the view
only fill_parent or an exact value in dip should be provided, while
wrap_content should not be used.
If the developer accidentally uses wrap_content, a warning message will be logged in
Logcat and the value will be changed:
• In case of width: It will be set to fill_parent.
• In case of height: It will be set to 50dip.
2012-12-18
Page 130 of 216
How to Set the Visibility of the Container (Android)
Visibility settings
The app developer may wish to hide the ad container at certain times in the app flow.
In order to do this the developer should use the setVisibility(int) method
which is defined for all android View objects.
However, it is recommended that the ad container is always notified about its visibility
from the point of view of the app user.
Example: The AdtechBannerView may be placed in a scrollable container, and even
though the view’s visibility is View.VISIBLE, the user of the app may not be able to
see the ad content because the AdtechBannerView is scrolled outside the device’s
viewport. In such cases if possible the app developer should notify the AdtechBannerView that the view is not viewable anymore/is viewable again via the setViewable(boolean) method.
2012-12-18
Page 131 of 216
How to Configure an Ad (Android)
Introduction
This topic describes how to configure an Android app to work with the ADTECH Mobile
SDK.
There are two types of configurations:
• Per app configuration: This is done in the Android manifest file of the app and provides general configuration for ad fetching.
• Per ad configuration: This is done dynamically at runtime and specifies configuration for a given ad container (AdtechBannerView or AdtechInterstitialView)
Per app configuration
When a banner or an interstitial view is created, the configuration is pre-filled with
some default values. These values are taken from the AndroidManifest.xml file and
they serve as a common base for the AdtechBannerView and AdtechInterstitialView.
This configuration is used internally by the ADTECH Mobile SDK when the ad request is
composed and sent. Failing to provide a valid configuration will result in a broken request.
Configuration that is specific to each banner is not placed in the manifest file, but it
can and must be set at runtime before calling the load method. Such a configuration
property for example is the alias and failing to set it will result in ad request failure and
the banner remaining empty.
For a more detailed overview on the default configuration see Ad Configuration for the
ADTECH Mobile SDK on page 38.
Manifest settings:
The configuration values should be added in the app’s manifest file as child nodes of
the <application> tag. Use the android <meta-data> key value xml tag to define
the required configuration values.
The values that have to be provided in the Android Manifest are the following:
Value Name
Value Type
adtech-appname
String
adtech-domain
String
adtech-network-id
Integer
adtech-subnetwork-id
Integer
adtech-animation-type
TOP_TO_BOTTOM, LEFT_TO_RIGHT, RIGHT_TO_LEFT,
FLIP_FROM_RIGHT, FLIP_FROM_LEFT, ANIMATION_NONE
adtech-refresh-interval
Integer [5,36000] (represents seconds)
Note: The value 0 means: Never refresh.
adtech-logging
V, D, I, W, E
adtech-open-landing-pages-t Boolean
hrough-browser
2012-12-18
Page 132 of 216
Configuration example:
<manifest>
...
<application>
...
<meta-data android:name="adtech-domain" android:value="a.adtech.de" />
<meta-data android:name="adtech-network-id" android:value="23" />
<meta-data android:name="adtech-subnetwork-id" android:value="5" />
<meta-data android:name="adtech-animation-type" android:value="TOP_TO_BOTTOM" />
<meta-data android:name="adtech-appname" android:value="TestApp" />
<meta-data android:name="adtech-refresh-interval" android:value="30" />
<meta-data android:name="adtech-logging" android:value="W" />
<meta-data android:name="adtech-open-landing-pages-through-browser" android:value="false" />
...
</application>
...
</manifest>
Per ad configuration
The developer may choose to configure an ad container dynamically in the Java code.
In order to do this an AdConfiguration instance has to be requested from the container. The developer may choose to overwrite the default values of alias, domain, networkId, subnetworkId, animation, groupId, imageBannerResizeEnabled, openLandingPagesThroughBrowser and refresh-interval.
// adtechView may be an instance of AdtechBannerView or AdtechInterstitialView
adtechView.getAdConfiguration().setDomain("a.adtech.de");
adtechView.getAdConfiguration().setNetworkId(13);
adtechView.getAdConfiguration().setSubnetworkId(4);
adtechView.getAdConfiguration().setAdAnimation(AdAnimation.FLIP_FROM_LEFT);
adtechView.getAdConfiguration().setRefreshInterval(10);
adtechView.getAdConfiguration().setGroupId(100);
adtechView.getAdConfiguration().setOpenLandingPagesThroughBrowser(false);
adtechView.getAdConfiguration().enableImageBannerResize(true);
2012-12-18
Page 133 of 216
How to Enable/Disable Image Banner Resize
How to
Enable/Disable
Image Banner Resize
Image banners may have different sizes faced to the ad container’s bounds (larger or
smaller) and developers can choose to resize the container to match the current ad’s
width and height. To do this the developer must call enableImageBannerResize(true) on the container’s AdConfiguration object.
This will enable automatic resizing on the container and after each resize the developer will be notified via the AdtechBannerViewCallback’s
onAdResize(ViewGroup.LayoutParams resizeParameters) method and may
update the application’s layout configurations to make sure that the resized banner fits
in.
By default this feature is disabled (set to false).
2012-12-18
Page 134 of 216
How to Use Direct Landing Page URLs (Android)
Enabling/disabling
usage of direct
landing page URLs
When a banner ad is clicked by the user the normal behavior is to open the browser
and load the landing page in it. In some instances the URL, that should be loaded in
the browser, is not pointing to the actual landing page but redirects to it. If the landing
page should happen to be a special URI (i.e tel:.., sms:.., mailto:.., geo:.., etc) which can
be handled by a native application on the device, the browser will launch the appropriate native app to handle the URI. In this case if the user closes the application that
has been launched, instead of returning to the app that is hosting the ad, the device
presents the blank web browser. Thus the user is forced to close the browser as well to
return to the application.
Application developers might wish to avoid this extra step (closing the browser as well)
when returning from the landing page hosting application, so a new methods have
been introduced in the BaseAdtechConfiguration API to enable or disable this behavior:
Method
Description
setOpenLandingPagesThrough- Provides the ability to enable opening of landing page URLs
OpenLandingPagesThroughvia the browser or directly in a native application.
Browser(boolean)
• If set to true: landing pages are launched directly in
browser. If the target landing page URL redirects to a
special link (e.g. tel:123456), the browser will launch
the intent for the appropriate application. If an application has been opened to handle a special link, then
leaving that app the browser will be in foreground with
a blank page above the app containing the ad.
• If set to false: the target landing page URL's redirects
are pre-processed to see if they contain a special link
(e.g. tel:123456). If there is no special link the
browser is launched, otherwise the native application
intent is called. If an application has been opened to
handle a special link, when leaving that app the app
containing the ad will be in foreground.
openLandingPagesThroughBrowserAllowed()
Returns the current setting for landing page opening behavior when ad is clicked.
Notes:
• Disabling this feature will add a small delay between the time the user clicks the ad
and the launching of the browser or application to handle the landing page URL.
• By default this feature is enabled (set to true).
2012-12-18
Page 135 of 216
How to Use Video Ads (Android)
Introduction
This topic describes how to add an ADTECH video view dynamically or as a resource
(via layout xml).
Procedure
Step
1.a
Action
Adding the video player as a member of your class
Create an AdtechVideoView instance:
// in your activity
AdtechVideoView videoView = new AdtechVideoView(context);
videoView.getConfiguration().setAdTypes(AdType.PRE_ROLL, AdType.MID_ROLL,
AdType.POST_ROLL);
Add the video view to your view hierarchy:
// request an instance to a layout manager (i.e RelatvieLayout, LinearLayout)
ViewGroup layout = ...;
LayoutParams lp = new LayoutParams(400, 400);
// add the video view to your view hierarchy
layout.addView(videoView, lp);
1.b
Adding the video player in a layout XML:
<com.adtech.mobilesdk.vast.AdtechVideoView
android:id="@+id/videoAd"
android:layout_width="fill_parent"
android:layout_height="200dip"
android:background="@android:color/black" >
</com.adtech.mobilesdk.vast.AdtechVideoView>
Create an AdtechVideoView instance in Java linked to the XML declaration:
AdtechVideoView videoView = (AdtechVideoView) findViewById(R.id.videoAd);
2
Set the path to the video file:
// set the video url
videoView.setVideoURI("http://path.to.my.video/video.mp4");
3
Configure the video view.
// configure the VAST request
AdType.POST_ROLL);
videoView.getConfiguration().setNetworkId(NETWORK_ID);
videoView.getConfiguration().setSubnetworkId(SUBNETWORK_ID);
videoView.getConfiguration().setPlacementId(PLACEMENT_ID);
videoView.getConfiguration().setDomain(DOMAIN_SERVER);
Note: Network id, subnetwork id and domain server can be set in the Android
Manifest file as well. For details see How to Configure an Ad (Android) on page
132.
2012-12-18
Page 136 of 216
Step
4.a
Action
Configure the video view for Linear Ad loading.
The setAdTypes method expects one or more type of ads. This means that you
can also call setAdTypes in the following ways:
// request all 3 ad types
AdType.POST_ROLL);
// request only mid roll
videoView.getConfiguration().setAdTypes(AdType.MID_ROLL);
// request pre roll and post roll
videoView.getConfiguration().setAdTypes(AdType.PRE_ROLL, AdType.POST_ROLL);
4.b
Configure the video view for Non Linear Ad loading.
To set the video view to fetch Non Linear ads which appear as overlays above the
video you must add NonLinearConfiguration objects to the AdtechVideoConfiguration instance of the video view. Each NonLinearConfiguration will result in the
request and obtaining of a non linear overlay.
NonLinearConfiguration nonLinearConfig = new NonLinearConfiguration();
// Set the duration of the overlay to 20 seconds.
nonLinearConfig.setDuration(20000);
// Place the overlay in the bottom of the video view
nonLinearConfig.setPlacement(Placement.BOTTOM);
// Set the margin from the bottom of the video view.
// In this case the margin will be 10% of the video view's height
nonLinearConfig.setPercentOfMargin(10);
// Set the time until the overlay becomes dismissible. In this case 10 seconds
nonLinearConfig.setSecondsUntilDismissible(10);
// Set the moment when the overlay should appear. In this case 5 seconds into video
playback.
nonLinearConfig.setStartTime(5000);
// Add the overlay configuration to the video view.
videoView.getConfiguration().addNonLinearConfig(nonLinearConfig);
5
Prepare playback:
// prepare video ads
videoView.prepare();
Take note that this method call is optional. If you call play() without calling prepare(), the AdtechVideoView will automatically call prepare() internally.
6
Play video:
// start video playback
// you can also call play from a button's OnClickListener.onClick() method.
videoView.play;
2012-12-18
Page 137 of 216
Step
7
Action
Receiving callback notifications (optional):
videoView.setVideoViewListener(new VideoViewListener() {
@Override
public void onPrepared() {
}
@Override
public void onError() {
}
@Override
public void onCompletion() {
}
});
This method should be called before prepare() and play().
2012-12-18
Page 138 of 216
How to Set the SDK Log Level (Android)
How to set the SDK
log level
The SDK logging level is a per app configuration. It is set in the Android Manifest file of
the app with the same meta data mechanism used for the ad network configuration.
<manifest>
...
<application>
...
<meta-data android:name="adtech-logging" android:value="W" />
...
</application>
...
</manifest>
Available logging
levels
The user can choose one of the following six logging levels:
Value
Logging Level
V
Verbose
D
Debug
I
Info
W
Warning
E
Error
OFF
Off
• The first logging level (Verbose) contains the most logs, including all the intermediate steps in downloading the ads, while choosing the last logging level (Error) enables logs only in the case of an error.
• If the logging level is not set, or if the value is not valid, logging will be turned off,
i.e. the logging level will be set to OFF.
• For debugging purposes, we recommend using the Debug or Verbose level.
2012-12-18
Page 139 of 216
How to Add Additional Key Value Parameters to the Ad Configuration
(Android)
Introduction
This topic shows how the developer can use custom user defined key value parameters to configure the banner or the interstitial.
Purpose of using
custom user defined
key value parameters
Besides the predefined ad configuration properties the user can add additional 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 configuration.
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.
Adding and removing
user defined key
values
The AdConfiguration class contains a set of specialized methods for adding and removing
key value pairs to the banner or interstitial configuration. The user can at any time inspect
the set of custom keys already defined and also inspect the values stored under those
keys. A key can store not only one but multiple values. Trying to add values with a key that
already exists, the value will not be duplicated in the configuration and the values will be
appended to the already existing ones. In case a value repeats itself it will be ignored.
Validation
When adding key value pairs, the ADTECH Mobile SDK validates and excludes the ones
that are not compliant. On failure a warning will be logged in Logcat.
• The maximum number of key value pairs that can be used on one ad is 26. If you
try to add more key values, a warning is logged and an error generated.
• As a general consideration, this key value pairs will be used for creating the ad request URL that has a length limitation of 4096. It might be that although the above
constraints are kept, still the URL to be too long (e.g. adding one key value pair,
where the value is an array with 128 tokens each with 48 chars). This will be ignored at URL construction and you will get a warning.
order might be different from that of the input array.
Code samples
// For banner ads
AdConfiguration adConfiguration = adtechBannerView.getAdConfiguration();
adConfiguration.addKeyValueParameter("Country", "DE");
adConfiguration.addKeyValueParameter("Gender", "Male");
adConfiguration.addKeyValueParameter("Age", "25");
// For video ads
AdtechVideoConfiguration vidaoAdConfiguration = adtechVideoView.getConfiguration();
vidaoAdConfiguration.addKeyValueParameter("Country", "DE");
vidaoAdConfiguration.addKeyValueParameter("Gender", "Male");
vidaoAdConfiguration.addKeyValueParameter("Age", "25");
2012-12-18
Page 140 of 216
How to Localize Messages Presented from the SDK (Android)
Localizing messages
There are different cases when the user is presented with an alert message (i.e no
network connection or calendar event creation) and the application developer may
wish to provide localized texts for these messages.
The following strings can be localized at the moment:
String
Default Text (English)
adtech_no_network
Please check your Internet connectivity.
adtech_confirm
OK
adtech_dont_allow
Don't Allow
adtech_location_permission
_prompt
Do you want to allow the ad to use your current location?
adtech_store_picture_prom
pt
Do you want to allow the ad to store a picture in your gallery?
adtech_store_screenshot_pr Do you want to allow the ad to take a screenshot and store it
ompt
in your gallery?
adtech_take_picture_promp
t
Do you want to allow the ad to take a picture with your camera and store it in your gallery?
adtech_create_calendar_eve Do you want to allow the ad to create an event in your calennt
dar?
These strings all have default texts (in English, visible next to each id) embedded in the
SDK, which will be used in the UI alerts if the application developer fails to provide
localized texts for them.
To provide localized texts for the strings mentioned above the developer must create a
strings.xml file in the appropriate values-[locale] directory within the android resources (res) directory.
Example (German)
If you want to add texts for the German locale you have to create a values-de directory in the res directory, and within it we will create a strings.xml file with the following entries:
<string name="adtech_no_network">Bitte überprüfen Sie Ihre Internetverbindung.</string>
<string name="adtech_confirm">Ja</string>
...
2012-12-18
Page 141 of 216
What You Need to Know for Your Android App to Work Well With the
SDK
Embedded proxy
server
Given the different implementations and APIs provided for the android.webkit.WebView class, an embedded web-server has been added to the
SDK for the implementation of the caching mechanism for ads. This web-server will
automatically run on devices with Android version lower then 3.0 (Honeycomb) as a
proxy.
The proxy web-server’s role is to listen for and intercept requests to resources that
have been cached by the SDK for cacheable and offline-enabled ads.
Please take note that the proxy server from the point of view of the user of the SDK is
totally transparent and will not affect the HTTP requests made by the Android application unless the requested URI points to a resource that has already been cached by the
SDK.
Unique device ID
The SDK uses a unique device ID which is stored on the device and shared among apps
using the ADTECH SDK. This device ID (appguid) is always sent to the ad server when
new ads are requested and loaded. The server uses this ID to identify a unique device,
this way it can find out that there are several applications running on the device which
use the ADTECH SDK, and the server can decide to serve ads appropriately.
However there are limitations to this unique ID. Since not every Android device has an
IMEI (noted in the official Android documentation) the SDK is forced to generate its
own unique ID which is stored in the app’s internal memory (sandbox) and on the removable SD card or external storage. Since the app’s internal memory can not be read
by other apps, the ID is always stored on the external memory so that all apps would
use this ID. Since there is a chance that the device might not have an external memory
it is possible that the apps will have different unique IDs.
This is a limitation until there will be a possibility to ask for a unique device id via an
android API.
2012-12-18
Page 142 of 216
2.3.3
In this section
The Public Interface (Android)
Topic
Page
Android Classes .................................................................................................. 144
2012-12-18
Page 143 of 216
Android Classes
Introduction
App developers are provided with the following public Java classes for adding ADTECH
ads to their application:
• com.adtech.mobilesdk.view
• com.adtech.mobilesdk.configuration
• com.adtech.mobilesdk.model
com.adtech.mobile
sdk.view
com.adtech.mobile
sdk.configuration
com.adtech.mobile
sdk.model
com.adtech.mobile
sdk.mediation.admob
com.adtech.mobilesdk.
mediation.greystripe
2012-12-18
Since: 1.0
Class Name
Description
AdtechInterstitialView
This view object is a view class that provides an MRAID complaint fullscreen ad container.
AdtechInterstitialViewCallback
Call-back interface used for notifying about basic Interstitial events, such
as success or failure in loading the advertisement.
AdtechBannerView
This view object is a view class that provides an MRAID compliant ad
container.
AdtechBannerViewCallback
Call-back interface used for notifying about basic banner events, such as
success or failure in loading the advertisement.
Since: 1.0
Class Name
Description
AdConfiguration
Configuration object for the behavior of the ad. This object may define
ad refresh intervals, ad provider types (i.e 3rd party ad providers such as
AdMob), ad provisioning rules, etc. Default values are provided but the
user can override them programmatically.
Since: 1.0
Class Name
Description
AdAnimation
Enumeration of the animations that can be applied when ads are
switched between them.
PlacementType
Defines the possible placement types for the ads.
Since: 2.1
Class Name
Description
AdmobConfiguration
Configuration for the Admob ads.
Since: 2.1
Class Name
Description
GreystripeConfiguration
Configuration for the Greystripe ads.
Page 144 of 216
com.adtech.mobile
sdk.mediation.millenial
com.adtech.mobile
sdk.mediation.vdopia
com.adtech.mobile
sdk.vast
Required classes
Since: 2.1
Class Name
Description
MillenialConfiguration
Configuration for the Millenial ads.
Since: 2.1
Class Name
Description
VdopiaConfiguration
Configuration for the Vdopia ads.
Since: 2.2
Class Name
Description
BaseAdtechConfiguration
Contains the basic adtech configuration information. (i.e domain, alias, network).
AdtechVideoView
Video player similar to the Android native VideoView which
provides an interface for VAST compliant ad serving.
AdtechVideoConfiguration
Configuration object for the requesting and behavior of VAST
ads.
AdType
Type of VAST ad.
VideoViewListener
Listener for video view events registered by the AdtechVideoView.
NonLinearConfiguration
Configuration object for the request and presentation of a Non
Linear VAST specific ads.
App developers are required to add an AdtechInterstitial or an AdtechBannerView to their activity to receive ADTECH ads, and they are required to implement
the appropriate callbacks to receive notifications regarding the two view types.
• The AdtechBannerView provides an Android specific view which can load
ADTECH banner ads. AdtechBannerView can be placed anywhere on the screen,
not only on the top or bottom. Most common AdtechView size is 320x50 pixels but
the developer can set any size as needed. These containers can be configured to
load new ads at specific time intervals.
• The AdtechInterstitialView provides an Android specific view for ads that
usually cover the full app UI, they are short lived full screen ad containers that can
be placed in different moments in an app (e.g. on app startup, when switching between 2 screens in the app) and they present only one ad and after that they expire
or are closed by the user, there is no refresh mechanism.
The AdConfiguration can be requested from an ADTECH banner or interstitial view
in order to change the default configurations.
2012-12-18
Page 145 of 216
2.3.4
In this section
How to Use Mediation for Third Party Advertisement SDKs
in Android
Topic
Page
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
2012-12-18
Page 146 of 216
How to Add a Third Party SDK (Android)
Add a 3rd party SDK to
be used by ADTECH
Mobile SDK
Step
Action
1
Download the SDK from the provider’s website.
2
Follow the instructions that are provided from the SDK to add the SDK to the project.
3
Configure the installed 3rd party SDK. You can choose from the following options:
• Use of the Android manifest file (for setting default values).
• Use the specific configuration objects inside AdConfiguration. Each supported
SDK will have a corresponding configuration object in AdConfiguration.
2012-12-18
Page 147 of 216
Supported Third Party SDK’s (Android)
Supported 3rd Party
SDK’s
The ADTECH Mobile SDK supports the following 3rd party SDK’s for mediation:
3rd Party SDK
Version
Download Link
4.5.1
http://developer.millennialmedia.com
2.0.1
http://wiki.ivdopia.com/home/integrating-android-sdk-v2
AdMob
Millennial Media
GreyStripe
Vdopia
2012-12-18
Page 148 of 216
AdMob Configuration in the ADTECH Mobile SDK (Android)
AndroidManifest.xml
configuration
In order for the Admob SDK to work appropriately make sure that the
com.google.ads.AdActivity is declared in the AndroidManifest.xml:
<activity
android:name="com.google.ads.AdActivity"
android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|sm
allestScreenSize" >
</activity>
The default configuration for AdMob may be placed in the AndroidManifest.xml
file as meta-data items or via an AdmobConfiguration object in the application
code. In both cases AdUnitId and Banner Size are required, while all the other settings are optional.
In the AndroidManifest.xml you can set the following parameters:
Sample code
Parameter
Description
AdUnitID
Your AdMob unit identifier. This is a mandatory parameter on any
banner or interstitial served by AdMob.
Banner size
The size of the banner. See more about this here
http://code.google.com/mobile/ads/docs/android/intermediate.
html#bannersizes.
Gender
The gender of the application user (if can be determined).
TestDevice
The id provided by AdMob in the android logcat for the device used
for testing. By setting this value you make sure your test devices will
not make false impressions. Additionally, there is always an ad
available for testing purposes. See more about this here
http://code.google.com/mobile/ads/docs/android/intermediate
.html#addtestdevice.

<meta-data
android:name="admob-config-size"
android:value="BANNER" />
<meta-data
android:name="admob-config-adunitid"
android:value="a14f27d03f5dbd4" />
<meta-data
android:name="admob-config-test-device"
android:value="511F71F55B1C9F2A7D1718C33E53635A" />
<meta-data
android:name="admob-config-gender"
android:value="MALE" />
2012-12-18
Page 149 of 216
Banner/interstitial
configuration
is provided, the default values from the configuration file are used. From code, by setting members of the AdmobConfiguration object (part of AdConfiguration), you can
additionally customize the following parameters:
•
•
•
•
Sample code
birthday
location
keywords
additional parameters
AdmobConfiguration admobConfiguration = adConfiguration.getAdmobConfiguration();
admobConfiguration.setAdSize(AdSize.IAB_BANNER);
admobConfiguration.setAdUnitId("<my_unit_id>");
// obtain the Admob specific adrequest and customize it
AdRequest adRequest = admobConfiguration.getAdRequest();
adRequest.setBirthday("<birthday_value>");
adRequest.setGender(Gender.FEMALE);
Map<String, Object> extras = ...;
adRequest.setExtras(extras);
Location location = ...;
adRequest.setLocation(location);
Set<String> keywords = ...;
adRequest.setKeywords(keywords);
Set<String> testDevices = ...;
adRequest.setTestDevices(testDevices);
For details about the meaning and usage of these parameters see AdMob’s page for
targeting here
http://code.google.com/mobile/ads/docs/android/intermediate.html#targeting.
Admob limitations
2012-12-18
Unlike the ADTECH Interstitial which is dismissed when the refresh interval from the
adtech server expires, Admob interstitials can not be dismissed automatically. The user
of the application must explicitly press the close button on the interstitial ad or press
the back button of the Android device in order to dismiss the interstitial.
Page 150 of 216
Millennial Configuration in the ADTECH Mobile SDK (Android)
AndroidManifest.xml
configuration
Two activities must be declared in the AndroidManifest.xml for the Millennial SDK to
work properly:
<activity
android:name="com.millennialmedia.android.MMAdViewOverlayActivity"
android:configChanges="keyboardHidden|orientation|keyboard"
android:theme="@android:style/Theme.Translucent.NoTitleBar" >
</activity>
<activity
android:name="com.millennialmedia.android.VideoPlayer"
android:configChanges="keyboardHidden|orientation|keyboard" >
</activity>
The default configuration for Millennial may be placed in the AndroidManifest.xml file
as meta-data items or via a MillennialConfiguration object in the application code. In
both cases APID is required, while all the other settings are optional.
In the AndroidManifest.xml you can set the following parameters:
2012-12-18
Parameter
Description
apid
unique id for a banner or interstitial placement.
adtype
type of the banner. This value is not required for interstitials. Possible string values are: MMBannerAdBottom, MMBannerAdTop and
MMBannerAdCenter.
age
in years (e.g. 18), or “unknown”
gender
“male”, “female”, or “unknown”
income
approximate number in US dollars (e.g. 65000).
zip
5 digit US zip code, or “unknown”
marital
Marital status, options are: “single”, “divorced”, “engaged”, “relationship”, “swinger”.
ethnicity
Options are: “hispanic”, “africanamerican”, “asian”, “indian”, “middleeastern”, “nativeamerican”, “pacificislander”, “white”, “other”
orientation
Sexual orientation, options are: “straight”, “gay”, “bisexual”, or
“notsure”.
children
Boolean (“true” or “false”), integer (e.g. 2), or “unknown”.
politics
Political views or party affiliation, options are: “republican”, “democrat”, “conservative”, “moderate”, “liberal”, “independent”, “other”,
or “unknown”.
education
Highest level of education, options are: “highschool”, “incollege”,
“somecollege”, “associate”, “bachelors”, “masters”, “phd”, “professional”, or “unknown”.
keywords
Any additional relevant description of the user or their preferences
separated by commas. e.g. “soccer,scores,basketball”.
Page 151 of 216
Sample Code
Parameter
Description
width
The width of the ad if you have a limit on the size of ads you can
display, e.g. 320. This should only be used if you have a specific limitation on the size of ads you can display. If not used, the ad returned will be optimized based on device specifications.
height
The height of the ad if you have a limit on the size of ads you can
display, e.g. 53. This should only be used if you have a specific limitation on the size of ads you can display. If not used, the ad returned will be optimized based on device specifications.
<meta-data android:name="millennial-config-apid" android:value="28911"/>
<meta-data android:name="millennial-config-adtype" android:value="MMBannerAdTop"/>
<meta-data android:name="millennial-config-age" android:value="25"/>
<meta-data android:name="millennial-config-children" android:value="no"/>
<meta-data android:name="millennial-config-education" android:value="bachelor"/>
<meta-data android:name="millennial-config-ethnicity" android:value="white"/>
<meta-data android:name="millennial-config-gender" android:value="male"/>
<meta-data android:name="millennial-config-height" android:value="53"/>
<meta-data android:name="millennial-config-width" android:value="320"/>
<meta-data android:name="millennial-config-income" android:value="50000"/>
<meta-data android:name="millennial-config-keywords"
android:value="soccer,baseball"/>
<meta-data android:name="millennial-config-marital" android:value="single"/>
<meta-data android:name="millennial-config-orientation" android:value="straight"/>
<meta-data android:name="millennial-config-politics" android:value="democrat"/>
<meta-data android:name="millennial-config-zip" android:value="94703"/>
Banner/interstitial
configuration
2012-12-18
is provided, the default values from the initial configuration are used. From code, by
setting members of the MillennialConfiguration object (part of AdConfiguration), you
can additionally customize all of the parameters described above via Java setter
methods, or you may choose to provide a hashtable with key-values for each paramater except the apid and adType.
Page 152 of 216
Sample code for
configuration with
setters
AdConfiguration adConfiguration = ...;
MillenialConfiguration millennialConfig = adConfiguration.getMillennialConfiguration();
millennialConfig.setApid("28911");
millennialConfig.setAdType(MMAdView.BANNER_AD_TOP);
millennialConfig.setAge("25");
millennialConfig.setChildren("no");
millennialConfig.setEducation("bachelor");
millennialConfig.setEthnicity("white");
millennialConfig.setGender("male");
millennialConfig.setHeight("53");
millennialConfig.setIncome("50000");
millennialConfig.setKeywords("soccer,baseball");
millennialConfig.setMarital("single");
millennialConfig.setOrientation("straight");
millennialConfig.setPolitics("democrat");
millennialConfig.setWidth("320");
millennialConfig.setZipCode("unknown");
Sample code for
configuration with
hashtable
MillenialConfiguration millennialConfig = adConfiguration.getMillennialConfiguration();
millennialConfig.setApid("28911");
millennialConfig.setAdType(MMAdView.BANNER_AD_TOP);
Hashtable<String, String> metaValues = new Hashtable<String, String>();
metaValues.put(MMAdView.KEY_AGE, "25");
metaValues.put(MMAdView.KEY_CHILDREN, "no");
metaValues.put(MMAdView.KEY_EDUCATION, "bachelor");
metaValues.put(MMAdView.KEY_ETHNICITY, "white");
metaValues.put(MMAdView.KEY_GENDER, "male");
metaValues.put(MMAdView.KEY_HEIGHT, "53");
metaValues.put(MMAdView.KEY_INCOME, "50000");
metaValues.put(MMAdView.KEY_KEYWORDS, "soccer,baseball");
metaValues.put(MMAdView.KEY_MARITAL_STATUS, "single");
metaValues.put(MMAdView.KEY_ORIENTATION, "straight");
metaValues.put(MMAdView.KEY_POLITICS, "democrat");
metaValues.put(MMAdView.KEY_WIDTH, "320");
metaValues.put(MMAdView.KEY_ZIP_CODE, "unknown");
millennialConfig.setMetaValues(metaValues);
Millennial limitations
2012-12-18
adtech server expires, Millennial interstitials can not be dismissed automatically. The
user of the application must explicitly press the close button on the interstitial ad or
press the back button of the Android device in order to dismiss the interstitial.
Page 153 of 216
Greystripe Configuration in the ADTECH Mobile SDK (Android)
Setting up the
Greystripe campaign
To integrate the Greystripe SDK in your applications, there are a couple of things that
need to be set up first. Most of the settings are done in the Android manifest file,
however, some of them can be done programatically also.
Adding the
Greystripe SDK
library to your
application project
The first thing you need to do to get Greystripe integration working is to add their
library to your application project. After creating your Greystripe account, you can get
the SDK here https://developer.greystripe.com/sdks. Then add the
gssdk_<version>.jar to your /libs project folder.
Application identifier
The first thing that needs to be configured in the Android manifest file is the application identifier received when creating your application on the Greystripe campaign
site. This is needed for successfully displaying the ads booked in your campaign. The
following code block shows how the application id metadata can be added to the
manifest file, in the <application> section. Replace
<YOUR-GREYSTRIPE-APPLICATION-ID> with your Greystripe application identifier.
Greystripe application identifier:
<meta-data
android:name="greystripe-app-id"
android:value="<YOUR-GREYSTRIPE-APPLICATION-ID>" />
The application identifier can also be provided programatically, by accessing your ad’s
AdConfiguration instance.
Setting up the application ID from code:
AdtechBannerView adTechView;
/* ... adTechView initialization ... */
adTechView.getAdConfiguration().getGreystripeConfiguration().setApplicationId("<YOUR-GREYSTR
IPE-APPLICATION-ID>");
Greystripe provider
and activity
declaration
Add the following in the <application> section, replacing
<YOUR_APPLICATION_PACKAGE> with a package identifier that is unique to your
application. This Content Provider manages local storage of ad content, while the Activity manages ad display.
Greystripe provider and activity declaration:
<provider
android:name="com.greystripe.android.sdk.AdContentProvider"
android:authorities="<YOUR_APPLICATION_PACKAGE>.AdContentProvider"
android:exported="false"
android:multiprocess="true" />
<activity
android:name="com.greystripe.android.sdk.AdView"
android:configChanges="keyboard|keyboardHidden|orientation" >
<intent-filter>
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
2012-12-18
Page 154 of 216
Permissions
declaration
There is a set of permissions needed for the Greystripe integration. Most of them are
required by the Greystripe SDK. However, the GET_TASKS permission is required by
the ADTECH SDK to figure out when the Greystripe interstitial ad has been dismissed,
and to notify the application developer accordingly.
Greystripe permissions:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
Example
The following code block represents a complete example of Greystripe SDK integration
that we used in our testing application. If using this code block, do not forget to update your application id and the provider authorities package name to your application
package name.

<meta-data
android:name="greystripe-app-id"
android:value="c0eec274-4051-4493-9991-5fc52f6f5a5a" />
<provider
android:name="com.greystripe.android.sdk.AdContentProvider"
android:authorities="com.adtech.mobilesdk.testerapp.AdContentProvider"
android:exported="false"
android:multiprocess="true" />
<activity
android:name="com.greystripe.android.sdk.AdView"
android:configChanges="keyboard|keyboardHidden|orientation" >
<intent-filter>
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
2012-12-18
Page 155 of 216
Vdopia Configuration in the ADTECH Mobile SDK (Android)
AndroidManifest.xml
configuration
The VDOWebActivity activity has to be declared in the AndroidManifest.xml for the
Vdopia SDK to work appropriately. Please take note that the Vdopia SDK will not throw
an exception (like Admob, Millennial, etc) if the activity is not declared.
<activity
android:configChanges="orientation|keyboardHidden"
android:name="com.vdopia.client.android.VDOWebActivity"
android:theme="@android:style/Theme.Translucent" >
</activity>
The following permissions are required by the SDK:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
The default configuration for Vdopia may be placed in the AndroidManifest.xml file as
meta-data items or via a VdopiaConfiguration object in the application code. In both
cases only the APIKEY is required and available.
You can set the apikey in the AndroidManifest.xml the following way:

<meta-data
android:name="vdopia-config-apikey"
android:value="AX123" />
Or you can set the APIKEY in Java code the following way:
VdopiaConfiguration vdopiaConfig = adConfiguration.getVdopiaConfiguration();
vdopiaConfig.setVdopiaKey("AX123");
Vdopia Limitations
2012-12-18
adtech server expires, Vdopia interstitials can not be dismissed automatically. The user
of the application must explicitly press the close button on the interstitial ad or press
the back button of the Android device in order to dismiss the interstitial.
Page 156 of 216
2.4
ADTECH Mobile SDK: Windows Phone
In this chapter
Topic
Page
How to Use the Mobile SDK in Windows Phone ................................................ 158
The Public Interface (Windows Phone) .............................................................. 173
Marketplace Submission Guidelines (Windows Phone) ..................................... 178
2012-12-18
Page 157 of 216
2.5
How to Use the Mobile SDK in Windows Phone
In this section
Topic
Page
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
2012-12-18
Page 158 of 216
How to Integrate the ADTECH Mobile SDK into Your Windows Phone
Application
Introduction
This topic describes how to integrate the ADTECH Mobile SDK into Windows Phone 7
applications.
Prerequisite
To use the ADTECH Mobile SDK for Windows Phone, Windows Phone version 7.5 or
higher is required.
Content of the SDK
.zip file
(ADTECHMobileSDK_
WindowsPhone_(ver
sion).zip)
How to add the
Adtech.Mobile.SDK.Li
brary.dll into your
Windows Phone
application
Folder
Description
Lib
Folder containing the Adtech.Mobile.SDK.Library.dll.
Docs
Folder containing the documentation for the SDK interface.
Sample
Folder containing a sample project where the SDK is used.
LICENSE.txt
ADTECHMobileSDK.
Step
1
Unpack the SDK archive file.
Note: It is recommended (but not mandatory) to copy the
Adtech.Mobile.SDK.Library.dll in your application folder, so you can easily reference it, and add it to source control.
2
2012-12-18
Action
Add a reference to the SDK library file: Right click the References folder in your
application project and browse to the location where you extracted/copied the
Adtech.Mobile.SDK.Library.dll file.
Page 159 of 216
Result: Once the library is referenced, you will notice that two additional controls have
been added to your toolbox: AdtechBannerControl and AdtechInterstitialControl:
That is it, you are all set. You can start using the controls, either from code, either by
dragging and dropping them in the .XAML editor / designer.
2012-12-18
Page 160 of 216
Banner and Interstitial Default Configuration (Windows Phone)
Introduction
This topic shows how to add a default configuration for all the ads in your application.
It is needed because some configuration parameters, like the application name, cannot be set directly on the placements and also because it eliminates the need of fully
configuring banners (see How to Add a Banner from XAML/Design Editor on page 163)
and interstitials (see How to Add an Interstitial Ad from XAML (Windows Phone) on
page 167), either from XAML or from code.
Adding the default
configuration
The default configuration can be added in the App.xaml file, under Application.Resources.
<Application
...

<Application.Resources>

<ResourceDictionary
xmlns:adtech="clr-namespace:Adtech.Windows.Phone.Sdk.Configuration;assembly=Adtech.Mobile.SD
K.Library">
<adtech:DefaultAdConfiguration x:Key="DefaultAdConfiguration"
Animation="TOP_TO_BOTTOM"
ApplicationName="SampleApplication"
Domain="a.adtech.de"
NetworkId="23"
SubnetworkId="4"
RefreshInterval="30"/>
</ResourceDictionary>
</Application.Resources>
...
</Application>
Setting the application name here is mandatory. All the other default parameters are
optional. This is a convenient way to configure all the banners and interstitial ads of an
application. It is worth mentioning that the individual banner / interstitial ad configuration overrides the default configuration. This means that the default configuration
for the optional fields is used only in the cases in which a mandatory property was not
set in the individual configuration (either in code or from XAML).
2012-12-18
Page 161 of 216
Out of all the configuration properties, only the alias cannot be added to the common
configuration file, since it is unique to each ad placement. This means that if the default configuration is in place, and all the ads in the application share the same configuration, the alias is the only property that needs to be set from code or XAML. We
strongly recommend adding the default configuration for all the configuration parameters, since it eliminates a lot of configuration code.
2012-12-18
Page 162 of 216
How to Add a Banner from XAML/Design Editor (Windows Phone)
Introduction
This topic describes how to add a banner from the XAML editor or directly from the
Design window.
Adding and
configuring the
banner
You can add the banner by dragging and dropping it from the toolbar in the design
editor, or by declaring the banner in XAML. If you want to declare it in XAML, you need
to add the ADTECH namespace at the top of your .xaml file, in the PhoneApplicationPage attributes.
<phone:PhoneApplicationPage
...
xmlns:adtech="clr-namespace:Adtech.Windows.Phone.Sdk.View;assembly=Adtech.Mobile.SDK.Library
"
...>
<Grid x:Name="LayoutRoot" Background="Transparent">
...
<adtech:AdtechBannerControl Name="bannerView"
NetworkId="23"
SubnetworkId="4"
RefreshInterval="30"
Alias="moby1-top-5"
/>
...
</Grid>
</phone:PhoneApplicationPage>
The next step is declaring the banner and configuring it. If the banner was dragged and
dropped from the toolbox within Visual Studio, only configuration is needed, since
both declaring the namespace and the control are automatically done by the IDE. Besides the ad configuration, you can add your custom UI configuration to the AdtechBannerControl, since it is a regular user control, supporting all the properties of
alignment, background color, etc.
Regarding the ad configuration, the code snippet shows how to do it all from XAML.
However, there are other ways to configure the banner, as you will see in future examples.
The alias is mandatory, since it is unique for each placement. If the other parameters
are not set here, they will be taken from the default configuration.
Loading the banner
After adding and configuring the banner, everything is in place for starting loading
those ads.
// Mandatory: Once the page is loaded, start displaying the ads.
Loaded += (s, e) => { bannerView.Load(); };
The code block above starts loading the ads, once the user control loaded within the
page. It can be added in the PhoneApplicationPage’s constructor.
2012-12-18
Page 163 of 216
Handling ad lifecycle
events
Although not mandatory, you can register event handlers for the ad container’s life
cycle events.
public SampleAd1()
{
InitializeComponent();
// Optional: register for ad events
bannerView.OnAdSuccess += new EventHandler(bannerView_OnAdSuccess);
bannerView.OnAdFailure += new EventHandler(bannerView_OnAdFailure);
bannerView.OnAdDefault += new EventHandler(bannerView_OnAdDefault);
bannerView.OnAdSuspend += new EventHandler(bannerView_OnAdSuspend);
bannerView.OnAdLeave += new EventHandler(bannerView_OnAdLeave);
bannerView.OnAdResume += new EventHandler(bannerView_OnAdResume);
}
void bannerView_OnAdResume(object sender, EventArgs e)
{
/**
* This method is called when the application has been resumed from the suspended
state.
*/
}
void bannerView_OnAdLeave(object sender, EventArgs e)
{
/**
* This method is called when the current application is left because the user clicked
* opened in a the external browser.
*/
}
void bannerView_OnAdDefault(object sender, EventArgs e)
{
/**
* This method is called when the default ad is loaded in the ad control.
*/
}
void bannerView_OnAdSuspend(object sender, EventArgs e)
{
/**
* This method is called to inform that the application should suspend its job, when
the advertisement has been
* resized and covers the whole screen. <p> This might be useful in applications like
games, or applications
* having video play-back.
*/
}
void bannerView_OnAdFailure(object sender, EventArgs e)
{
/**
2012-12-18
Page 164 of 216
* This method is called when an ad download failed. This could happen because of
networking reasons or other
* server or internal reasons.
*/
}
void bannerView_OnAdSuccess(object sender, EventArgs e)
{
/**
* This method is called when an ad was downloaded successfully.
*/
}
}
The code block is a snippet from the sample application bundled with the SDK. It
shows how to register for all the supported banner events: success, failure, default,
suspend, failure, resume.
Informing the ad
container about
visibility changes
This could have been done automatically by the SDK. However, when working on the
feature, we decided that it is best for the application developer to have a choice, due
to several reasons. Loading the ad in the background and presenting it only when it is
visible is one of them. Thus, although not necessary, it is recommended that you inform the ad container about visibility changes, by using the banner’s Viewable property.
// Update the Viewable property whenever the visibility of the banner changes.
// Set it to false when the banner is not visible, and reset it to true (default value) when the
view becomes visible again.
bannerView.Viewable = false;
2012-12-18
Page 165 of 216
How to Add a Banner Entirely from Code (Windows Phone)
Introduction
This topic shows how to add and configure a banner entirely from code. This might be
useful in cases in which the content of one page is dynamic, and you cannot know at
design/compile time how your phone application page is going to look like.
Adding and
configuring the
banner
For this example, we make an assumption that the banner that we want to create will
be added to the UI in a list, already present in the page.
// Create a new ad banner and set its configuration properties.
AdtechBannerControl adtechBannerControl = new AdtechBannerControl();
// Mandatory: set the campaign alias.
adtechBannerControl.Alias = "moby2-top-5";
// Mandatory if the domain, network id and subnetwork id are not configured in .xaml
adtechBannerControl.Domain = "a.adtech.de";
adtechBannerControl.NetworkId = 23;
adtechBannerControl.SubnetworkId = 4;
/**
* Optional: set the control refresh interval and animation. If not set, they will be set to default
values. However,
* values coming from the ad server can override these values.
*/
adtechBannerControl.Animation = AdAnimation.FLIP_FROM_LEFT;
adtechBannerControl.RefreshInterval = 10;
// Mandatory: start loading the ads once the banner is loaded.
adtechBannerControl.Loaded += (s, e) => { adtechBannerControl.Load(); };
// Add the banner to the list box
sampleListBox.Items.Insert(0, adtechBannerControl);
The first line of code creates the banner by using the default constructor. Following,
the banner is configured with mandatory and optional properties. In the end, the
banner is loaded (mandatory step) and added to a ListBox control, named sampleListBox.
Handling lifecycle
events
For handling events during an ads life cycle, see Handling ad lifecycle events in How to
Add a Banner from XAML/Design Editor (Windows Phone) on page 163.
Visibility changes
For keeping the Viewable property up to date, see Informing the ad container about
visibility changes in How to Add a Banner from XAML/Design Editor (Windows Phone)
on page 163
2012-12-18
Page 166 of 216
How to Add an Interstitial Ad from XAML (Windows Phone)
Introduction
This topic shows how to integrate an interstitial in your application from the designer/XAML.
Adding and
configuring the
interstitial
Similar to the integration of a banner, a minimal amount of configuration is needed in
order to include an interstitial ad in your application.
First, you need to declare the ADTECH namespace at the top of your .xaml file, as a
PhoneApplicationPage attribute.
Second, you need to place the interstitial configuration attributes within the declaration of the interstitial. We recommend stretching the ad horizontally and vertically, but
this is not mandatoy. The following code snipped shows an example of how to declare
and configure your interstitial from .xaml:
<phone:PhoneApplicationPage
...

xmlns:adtech="clr-namespace:Adtech.Windows.Phone.Sdk.View;assembly=Adtech.Mobile.SDK.Library
"
... >
<Grid x:Name="LayoutRoot" >
...

<adtech:AdtechInterstitialControl
NetworkId="23"
SubnetworkId="4"
HorizontalAlignment="Stretch"
VerticalAlignment="Stretch"
Name="sampleInterstitial" />
...
</Grid>
</Grid>
</phone:PhoneApplicationPage>
Loading the
interstitial
The next step is loading the interstitial. It is done similar to loading a banner, by registering a handler for the load event.
Loaded += (s, e) => { sampleInterstitial.Load(); };
2012-12-18
Page 167 of 216
Interstitial lifecycle
events
For notifications about the interstitial life cycle events, you need to register event handlers on the interstitial control. Following is a snippet from the sample application
delivered with the SDK, showing how to react to all interstitial events.
public partial class InterstitialAd : PhoneApplicationPage
{
public InterstitialAd()
{
/** Optional: register for ad events */
sampleInterstitial.OnAdSuccess += new
EventHandler(sampleInterstitial_OnAdSuccess);
sampleInterstitial.OnAdFailure += new
EventHandler(sampleInterstitial_OnAdFailure);
sampleInterstitial.OnAdDefault += new
EventHandler(sampleInterstitial_OnAdDefault);
sampleInterstitial.OnAdDismiss += new
EventHandler(sampleInterstitial_OnAdDismiss);
sampleInterstitial.OnAdLeave += new EventHandler(sampleInterstitial_OnAdLeave);
/** Mandatory: start loading the ad */
}
void sampleInterstitial_OnAdDismiss(object sender, EventArgs e)
{
/**
* This method is called when the expires and the interstitial view is dismissed.
*/
}
void sampleInterstitial_OnAdLeave(object sender, EventArgs e)
{
/**
*/
}
void sampleInterstitial_OnAdDefault(object sender, EventArgs e)
{
/**
*/
}
void sampleInterstitial_OnAdFailure(object sender, EventArgs e)
{
/**
*/
}
2012-12-18
Page 168 of 216
void sampleInterstitial_OnAdSuccess(object sender, EventArgs e)
{
/**
*/
}
}
An important event in the case of the interstitial ad is the OnAdDismiss event. This
event occurs when the interstitial times out and the ad disappears from the screen.
If using the interstitial for navigating from one screen to the other, this is the moment
when the content on the new screen should be ready for interaction.
Interstitial visibility
changes
2012-12-18
Similar to the banner visibility changes, it is recommended that you follow the same
rules for the interstitial ad. By doing so, the interstitials timer will pause whenever the
interstitial is not visible, and resume when it becomes visible again. For details see
Informing the ad container about visibility changes in How to Add a Banner from
XAML/Design Editor (Windows Phone) on page 163
Page 169 of 216
How to Add an Interstitial Entirely from Code (Windows Phone)
How to add an
interstitial from code
An interstitial ad can be added entirely from code as well. In a similar manner to adding a banner from code (see How to Add a Banner Entirely from Code (Windows
Phone) on page 166), two extra steps are needed. First, the interstitial ad needs to be
constructed, and second, it needs to be added to the layout root.
public partial class InterstitialAd : PhoneApplicationPage
{
{
/** Construct the new interstitial. */
AdtechInterstitialControl sampleInterstitial = new AdtechInterstitialControl();
/** Mandatory: configure the interstitial.*/
sampleInterstitial.Alias = "interstitial-top-5";
sampleInterstitial.Domain = "a.adtech.de";
sampleInterstitial.NetworkId = 23;
sampleInterstitial.SubnetworkId = 4;
sampleInterstitial.RefreshInterval = 30;
/** Optional: register for ad events. */
/** Mandatory: Add the interstitial to the layout root, or to a children of the layout
root. */
LayoutRoot.Children.Add(sampleInterstitial);
}
{
/*
* This method is called when the timer expires and the interstitial view is dismissed.
*/
}
{
/*
2012-12-18
Page 170 of 216
*/
}
{
/*
*/
}
{
/*
*/
}
{
/*
*/
}
}
The previous code block shows how to configure and load an interstitial from code
exclusively. In this case, we do not need to declare the interstitial in the XAML file.
Although there is a lot of code involving the registration for interstitial life-cycle
events, it is absolutely optional to handle those events.
2012-12-18
Page 171 of 216
How to Add Additional Key-value Parameters to the Ad Configuration
(Windows Phone)
Introduction
This topic shows how to add additional key-value parameters to the ad configuration.
These parameters are sent to the ad server together with the request for a new ad,
such that the ad can better target the users.
Code sample
// Add a single key-value parameter
bannerViewMraid.AddKeyValueParameter("country", "DE");
// Add multiple values for one key
bannerViewMraid.AddKeyValueParameter("country", "DE", "US", "FR");
The first example shows how to add one key-value pair, while the second shows a
convenient method for adding multiple values for one key.
2012-12-18
Page 172 of 216
2.6
The Public Interface (Windows Phone)
In this section
Topic
Page
Windows Phone Class: BaseAdtechControl........................................................ 174
Windows Phone Class: AdtechBannerControl.................................................... 175
Windows Phone Class: AdtechInterstitialControl ............................................... 176
Windows Phone Enums ...................................................................................... 177
2012-12-18
Page 173 of 216
Windows Phone Class: BaseAdtechControl
• Name: BaseAdtechControl
• Inherits: UserControl
About the class
Description:
Base user control class containing the common behavior of the ADTECH ad containers.
Public Interface
Member
Type
Since
Description
OnAdDefault
event
1.0
Occurs when the default ad is loaded in the AdtechBannerControl container.
OnAdSuccess
event
1.0
Occurs when an ad was downloaded successfully
OnAdFailure
event
1.0
Occurs when an ad download failed. This could happen because of
networking reasons or other server communication reasons.
OnAdLeave
event
1.0
Occurs when the current application is left because the user clicked a
banner which will be opened in the external browser.
Viewable
Boolean property
1.0
Informs the ADTECH SDK when this view goes out of the screen or
becomes invisible. This is useful for enabling/disabling certain resource or network-consuming operations that are part of the ad
loading process.
Alias
String property
1.0
Alias of the placement.
RefreshInterval
String property
1.0
Refresh interval of the placement.
GroupId
Int32? property
1.0
Group ID of the placement. Two placements can be identified as being part of the same page by setting the same group id to each of
them.
NetworkId
Int32? property
1.0
Network ID of the placement.
SubnetworkId
Int32? property
1.0
Sub-network ID of the placement.
Animation
AdAnimation?
property
1.0
Animation used for transitioning between ads.
Domain
String property
1.0
The ad server domain.
2012-12-18
Page 174 of 216
Windows Phone Class: AdtechBannerControl
About the class
• Name: AdtechBannerControl
• Inherits: BaseAdtechControl
Description:
This is a view class that provides an MRAID compliant ad container. It represents the
primary gateway between the ADTECH SDK and the user of the SDK (application developer).
More than one such view can be used at a time and they are independent from one
another.
You can register to multiple banner life cycle events through the described public interface.
Public Interface
Member
Type
Since
Description
AdtechBannerControl()
constructor
1.0
Constructs a new ad banner.
OnAdSuspend
event
1.0
Occurs when the application should suspend its job, because
the advertisement has been expanded and covers the whole
screen. This might be useful in games, or video play-back
apps.
OnAdResume
event
1.0
This event occurs when the ad has been resumed in the default state.
Load()
method
1.0
Starts loading the ads.
AddKeyValueParameter(String key, params
String[] values)
method
1.0
Adds extra key value parameters to the add configuration.
Parameters:
• key: The key of the parameter.
• values: One or more value parameters.
2012-12-18
Page 175 of 216
Windows Phone Class: AdtechInterstitialControl
About the class
• Name: AdtechInterstitialControl
Description:
This is a full-screen MRAID ad container. Each interstitial ad should be added by creating one instance of this class.
Interstitial ads are usually used when a time-intensive operation is in process, like
loading a game. The user will be engaged in the ad while waiting for the process to
finish.
Public Interface
Member
Type
Since
Description
AdtechInterstitialControl()
constructor
1.0
Constructs a new interstitial control.
OnAdDismiss
event
1.0
Occurs when the interstitial timer expires and the user should
dismiss/hide the view.
2012-12-18
Page 176 of 216
Windows Phone Enums
About the enum
• Name: AdAnimation
Description:
Defines the possible animations for the Windows Phone SDK ad transitions.
Public Interface
2012-12-18
Name
Since
Description
NONE
1.0
No animation used for switching the ads.
TOP_TO_BOTTOM
1.0
The ads are going to be switched by animating the new incoming ads from the top to the bottom of the container.
LEFT_TO_RIGHT
1.0
The ads are going to be switched by animating the new incoming ads from the left to the right of the container.
RIGHT_TO_LEFT
1.0
The ads are going to be switched by animating the new incoming ads from the right to the left of the container.
FLIP_FROM_RIGHT
1.0
New ads are going to be flipped in from the right side of the
container. Old ads are going to be flipped out.
FLIP_FROM_LEFT
1.0
New ads are going to be flipped in from the left side of the
Page 177 of 216
2.7
Marketplace Submission Guidelines (Windows Phone)
In this section
Topic
Page
Application Policies for the Windows Phone Marketplace ................................ 179
2012-12-18
Page 178 of 216
Application Policies for the Windows Phone Marketplace
Introduction
This topic provides information regarding the marketplace submission process with
regard to the ad content within your app.
Application policies
As you probably know, the Windows Phone Marketplace submission process validates
and approves your app before it is available on the market. The submission process
has some rules regarding the:
• application performance
• application and ad content
• application behavior
The Windows Phone SDK was optimized regarding application performance and
memory issues so that there are no leaks due to the SDK integration in your app. The
application behavior is the responsibility of the application developer. However, with
regard to application and ad content, there are some considerations:
• “Your application may not sell, link to, or otherwise promote mobile voice plans.”
• “If your application includes or displays advertising, the advertising must comply
with the Microsoft Advertising Creative Acceptance Policy Guide
http://advertising.microsoft.com/WWDocs/User/en-us/CAP/External/External_Low
/index.html and the application must have distinct, substantial and legitimate content and purpose other than the display of advertising.”
All the rules, including the two above can be found in the Windows Phone Dev Center
http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh184843%28v=vs.
92%29.
2012-12-18
Page 179 of 216
2.8
ADTECH Mobile SDK: Windows 8
In this chapter
Topic
Page
Getting Started with the ADTECH Mobile SDK (Windows 8) .............................. 181
How to Use the Mobile SDK in Windows 8 ........................................................ 186
The Public Interface (Windows 8) ...................................................................... 198
Windows Store Submission Guidelines (Windows 8) ......................................... 203
2012-12-18
Page 180 of 216
2.8.1
In this section
Getting Started with the ADTECH Mobile SDK (Windows 8)
Topic
Page
How to Integrate the ADTECH Mobile SDK into Your Windows 8 Store Application
............................................................................................................................ 182
ADTECH Mobile SDK Release Notes (Windows 8) .............................................. 185
2012-12-18
Page 181 of 216
How to Integrate the ADTECH Mobile SDK into Your Windows 8 Store
Application
Introduction
This topic describes how to integrate the ADTECH Mobile SDK into Windows 8 Store
applications.
Prerequisite
To use the ADTECH Mobile SDK for Windows 8, Windows 8 or higher is required.
Content of the SDK
.zip file
(ADTECHSDK_Windo
ws8_(version).zip)
How to add the
Adtech.Windows8.
SDK.dll into your
Windows 8 Store
application
Folder
Description
Lib
Folder containing the Adtech.Windows8.SDK.Library.dll.
Docs
Folder containing the documentation for the SDK interface.
Sample
Folder containing a sample project where the SDK is used.
LICENSE.txt
ADTECH Mobile SDK.
Step
1
Unpack the SDK archive file.
Note: It is recommended (but not mandatory) to copy the
Adtech.Windows8.SDK.dll in your application folder, so you can easily reference it,
and add it to source control.
2
2012-12-18
Action
Add a reference to the SDK library file: Right click the References folder in your
application project and browse to the location where you extracted/copied the
Adtech.Windows8.SDK.dll file.
Page 182 of 216
Step
Action
3
Right click on the General tab and click on Choose Items… to add controls to your
toolbox:
4
In the Choose Toolbox Items window, select the Windows XAML Components tab
and browse again to the location where you extracted/copied the
Adtech.Windows8.SDK.dll:
Result: Two additional controls AdtechBannerControl and AdtechInterstitialControl have been added.
2012-12-18
Page 183 of 216
Step
Action
5
Click Ok.
Result: The two controls will appear on your toolbox in the General tab:
That is it, you are all set. You can start using the controls, either from code, either by
dragging and dropping them in the .XAML editor / designer.
2012-12-18
Page 184 of 216
ADTECH Mobile SDK Release Notes (Windows 8)
Release 1.0.1
Maintenance
• Fixed an issue regarding the call of expand() while in an interstitial, which should
have no effect.
• Removed the extra top row used for showing the default SDK’s custom close button. The button is now shown as an overlay over the ad view.
2012-12-18
Page 185 of 216
2.9
How to Use the Mobile SDK in Windows 8
In this section
Topic
Page
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 186 of 216
Banner and Interstitial Default Configuration (Windows 8)
Introduction
This topic shows how to add a default configuration for all the ads in your application.
It is needed because some configuration parameters, like the application name, cannot be set directly on the placements and also because it eliminates the need of fully
configuring banners (see How to Add a Banner from XAML/Design Editor on page 188)
and interstitials (see How to Add an Interstitial Ad from XAML (Windows 8) on page
192), either from XAML or from code.
Adding the default
configuration
The default configuration can be added in the App.xaml file, under Application.Resources.
<Application
...

<Application.Resources>

<ResourceDictionary xmlns:local="using:Adtech.Windows8.SDK.Configuration">
<local:DefaultAdConfiguration x:Key="DefaultAdConfiguration"
ApplicationName="SampleApplication"
NetworkId="23"
SubnetworkId="4"
RefreshInterval="30"/>
</ResourceDictionary>
</Application.Resources>
...
</Application>
Setting the application name here is mandatory. All the other default parameters are
optional. This is a convenient way to configure all the banners and interstitial ads of an
application. It is worth mentioning that the individual banner / interstitial ad configuration overrides the default configuration. This means that the default configuration
for the optional fields is used only in the cases in which a mandatory property was not
set in the individual configuration (either in code or from XAML).
Out of all the configuration properties, only the alias cannot be added to the common
configuration file, since it is unique to each ad placement. This means that if the default configuration is in place, and all the ads in the application share the same configuration, the alias is the only property that needs to be set from code or XAML. We
strongly recommend adding the default configuration for all the configuration parameters, since it eliminates a lot of configuration code.
2012-12-18
Page 187 of 216
How to Add a Banner from XAML/Design Editor (Windows 8)
Introduction
This topic describes how to add a banner from the XAML editor or directly from the
Design window.
Adding and
configuring the
banner
You can add the banner by dragging and dropping it from the toolbar in the design
editor, or by declaring the banner in XAML. If you want to declare it in XAML, you need
to add the ADTECH namespace at the top of your .xaml file, in the very top tag of current page, in our example I chose a page of LayoutAwarePage type so the ADTECH
namespace will be added among LayoutAwarePage attributes.
<common:LayoutAwarePage
...
xmlns:adtech="using:Adtech.Windows8.SDK.View"
...>
<Grid x:Name="LayoutRoot" Background="Transparent">
...
<adtech:AdtechBannerControl Name="bannerView"
NetworkId="23"
SubnetworkId="4"
Alias="moby1-top-5"/>
...
</Grid>
</common:LayoutAwarePage>
The next step is declaring the banner and configuring it. If the banner was dragged and
dropped from the toolbox within Visual Studio, only configuration is needed, since
both declaring the namespace and the control are automatically done by the IDE. Besides the ad configuration, you can add your custom UI configuration to the AdtechBannerControl, since it is a regular user control, supporting all the properties of
alignment, background color, etc.
Regarding the ad configuration, the code snippet shows how to do it all from XAML.
However, there are other ways to configure the banner, as you will see in future examples.
Loading the banner
After adding and configuring the banner, everything is in place for starting loading
those ads.
The code block above starts loading the ads, once the user control loaded within the
page. It can be added in the MainApplicationPage’s constructor.
2012-12-18
Page 188 of 216
Handling ad lifecycle
events
Although not mandatory, you can register event handlers for the ad container’s life
cycle events.
public SampleAd1()
{
// Optional: register for ad events
bannerView.OnAdSuccess += new EventHandler(bannerView_OnAdSuccess);
bannerView.OnAdFailure += new EventHandler(bannerView_OnAdFailure);
bannerView.OnAdDefault += new EventHandler(bannerView_OnAdDefault);
bannerView.OnAdSuspend += new EventHandler(bannerView_OnAdSuspend);
bannerView.OnAdLeave += new EventHandler(bannerView_OnAdLeave);
bannerView.OnAdResume += new EventHandler(bannerView_OnAdResume);
}
void bannerView_OnAdResume(object sender, EventArgs e)
{
/**
* This method is called when the application has been resumed from the suspended
state.
*/
}
void bannerView_OnAdLeave(object sender, EventArgs e)
{
/**
*/
}
void bannerView_OnAdDefault(object sender, EventArgs e)
{
/**
*/
}
void bannerView_OnAdSuspend(object sender, EventArgs e)
{
/**
* This method is called to inform that the application should suspend its job, when
the advertisement has been
* resized and covers the whole screen. <p> This might be useful in applications like
games, or applications
* having video play-back.
*/
}
void bannerView_OnAdFailure(object sender, EventArgs e)
{
/**
2012-12-18
Page 189 of 216
*/
}
void bannerView_OnAdSuccess(object sender, EventArgs e)
{
/**
*/
}
}
The code block is a snippet from the sample application bundled with the SDK. It
shows how to register for all the supported banner events: success, failure, default,
suspend, failure, resume.
Informing the ad
container about
visibility changes
This could have been done automatically by the SDK. However, when working on the
feature, we decided that it is best for the application developer to have a choice, due
to several reasons. Loading the ad in the background and presenting it only when it is
visible is one of them. Thus, although not necessary, it is recommended that you inform the ad container about visibility changes, by using the banner’s Viewable property.
// Update the Viewable property whenever the visibility of the banner changes.
// Set it to false when the banner is not visible, and reset it to true (default value) when the
view becomes visible again.
bannerView.Viewable = false;
2012-12-18
Page 190 of 216
How to Add a Banner Entirely from Code (Windows 8)
Introduction
This topic shows how to add and configure a banner entirely from code. This might be
useful in cases in which the content of one page is dynamic, and you cannot know at
design/compile time how your Windows 8 application page is going to look like.
Adding and
configuring the
banner
For this example, we make an assumption that the banner that we want to create will
be added to the UI in a list, already present in the page.
// Create a new ad banner and set its configuration properties.
AdtechBannerControl adtechBannerControl = new AdtechBannerControl();
// Mandatory: set the campaign alias.
adtechBannerControl.Alias = "moby2-top-5";
// Mandatory if the domain, network id and subnetwork id are not configured in .xaml
adtechBannerControl.Domain = "a.adtech.de";
adtechBannerControl.NetworkId = 23;
adtechBannerControl.SubnetworkId = 4;
/**
* Optional: set the control refresh interval and animation. If not set, they will be set to default
values. However,
* values coming from the ad server can override these values.
*/
adtechBannerControl.Animation = AdAnimation.FLIP_FROM_LEFT;
adtechBannerControl.RefreshInterval = 10;
// Mandatory: start loading the ads once the banner is loaded.
adtechBannerControl.Loaded += (s, e) => { adtechBannerControl.Load(); };
// Add the banner to the list box
SampleListBox.Items.Insert(0, adtechBannerControl);
The first line of code creates the banner by using the default constructor. Following,
the banner is configured with mandatory and optional properties. In the end, the
banner is loaded (mandatory step) and added to a ListBox control, named sampleListBox.
Handling lifecycle
events
For handling events during an ads life cycle, see Handling ad lifecycle events in How to
Add a Banner from XAML/Design Editor (Windows 8) on page 188.
Visibility changes
For keeping the Viewable property up to date, see Informing the ad container about
visibility changes in How to Add a Banner from XAML/Design Editor (Windows 8) on
page 188.
2012-12-18
Page 191 of 216
How to Add an Interstitial Ad from XAML (Windows Phone)
Introduction
This topic shows how to integrate an interstitial in your application from the designer/XAML.
Adding and
configuring the
interstitial
Similar to the integration of a banner, a minimal amount of configuration is needed in
order to include an interstitial ad in your application.
First, you need to declare the ADTECH namespace at the top of your .xaml file, as a
LayoutAwarePage attribute.
Second, you need to place the interstitial configuration attributes within the declaration of the interstitial. We recommend stretching the ad horizontally and vertically, but
this is not mandatoy. The following code snipped shows an example of how to declare
and configure your interstitial from .xaml:
<common:LayoutAwarePage
...

xmlns:adtech="using:Adtech.Windows8.SDK.View"
... >
<Grid x:Name="LayoutRoot" >
...

<adtech:AdtechInterstitialControl
NetworkId="23"
SubnetworkId="4"
HorizontalAlignment="Stretch"
VerticalAlignment="Stretch"
Name="sampleInterstitial" />
...
</Grid>
</Grid>
</common:LayoutAwarePage>
Loading the
interstitial
The next step is loading the interstitial. It is done similar to loading a banner, by registering a handler for the load event.
2012-12-18
Page 192 of 216
Interstitial lifecycle
events
For notifications about the interstitial life cycle events, you need to register event handlers on the interstitial control. Following is a snippet from the sample application
delivered with the SDK, showing how to react to all interstitial events.
public partial class InterstitialAd
{
{
/** Optional: register for ad events */
}
{
/**
* This method is called when the expires and the interstitial view is dismissed.
*/
}
{
/**
*/
}
{
/**
*/
}
{
/**
*/
}
2012-12-18
Page 193 of 216
{
/**
*/
}
}
An important event in the case of the interstitial ad is the OnAdDismiss event. This
event occurs when the interstitial times out and the ad disappears from the screen.
If using the interstitial for navigating from one screen to the other, this is the moment
when the content on the new screen should be ready for interaction.
Interstitial visibility
changes
2012-12-18
Similar to the banner visibility changes, it is recommended that you follow the same
rules for the interstitial ad. By doing so, the interstitials timer will pause whenever the
interstitial is not visible, and resume when it becomes visible again. For details see
Informing the ad container about visibility changes in How to Add a Banner from
XAML/Design Editor (Windows 8) on page 188
Page 194 of 216
How to Add an Interstitial Entirely from Code (Windows 8)
How to add an
interstitial from code
An interstitial ad can be added entirely from code as well. In a similar manner to adding a banner from code (see How to Add a Banner Entirely from Code (Windows 8) on
page 191), two extra steps are needed. First, the interstitial ad needs to be constructed, and second, it needs to be added to the layout root.
public partial class InterstitialAd
{
{
/** Construct the new interstitial. */
AdtechInterstitialControl sampleInterstitial = new AdtechInterstitialControl();
/** Mandatory: configure the interstitial.*/
sampleInterstitial.Alias = "interstitial-top-5";
sampleInterstitial.Domain = "a.adtech.de";
sampleInterstitial.NetworkId = 23;
sampleInterstitial.SubnetworkId = 4;
sampleInterstitial.RefreshInterval = 30;
/** Optional: register for ad events. */
/** Mandatory: Add the interstitial to the layout root, or to a children of the layout
root. */
LayoutRoot.Children.Add(sampleInterstitial);
}
{
/*
* This method is called when the timer expires and the interstitial view is dismissed.
*/
}
{
/*
2012-12-18
Page 195 of 216
*/
}
{
/*
*/
}
{
/*
*/
}
{
/*
*/
}
}
The previous code block shows how to configure and load an interstitial from code
exclusively. In this case, we do not need to declare the interstitial in the XAML file.
Although there is a lot of code involving the registration for interstitial life-cycle
events, it is absolutely optional to handle those events.
2012-12-18
Page 196 of 216
How to Add Additional Key-value Parameters to the Ad Configuration
(Windows 8)
Introduction
This topic shows how to add additional key-value parameters to the ad configuration.
These parameters are sent to the ad server together with the request for a new ad,
such that the ad can better target the users.
Code sample
// Add a single key-value parameter
bannerViewMraid.AddKeyValueParameter("country", "DE");
// Add multiple values for one key
bannerViewMraid.AddKeyValueParameter("country", "DE", "US", "FR");
The first example shows how to add one key-value pair, while the second shows a
convenient method for adding multiple values for one key.
2012-12-18
Page 197 of 216
2.10
The Public Interface (Windows 8)
About the public
interface
This section describes the classes of the ADTECH SDK for Windows 8, their public interface, events, properties and all the used enumerations and constants.
In this section
Topic
Page
Windows 8 Class: BaseAdtechControl ................................................................ 199
Windows 8 Class: AdtechBannerControl ............................................................ 200
Windows 8 Class: AdtechInterstitialControl ....................................................... 201
Windows 8 Enums .............................................................................................. 202
2012-12-18
Page 198 of 216
Windows 8 Class: BaseAdtechControl
• Name: BaseAdtechControl
• Inherits: UserControl
• Since: 1.0
About the class
Description:
Base user control class containing the common behavior of the ADTECH ad containers.
Public Interface
Member
Type
Since
Description
OnAdDefault
event
1.0
Occurs when the default ad is loaded in the AdtechBannerControl container.
OnAdSuccess
event
1.0
Occurs when an ad was downloaded successfully
OnAdFailure
event
1.0
Occurs when an ad download failed. This could happen because of
networking reasons or other server communication reasons.
OnAdLeave
event
1.0
Occurs when the current application is left because the user clicked a
banner which will be opened in the external browser.
Viewable
bool property
1.0
Informs the ADTECH SDK when this view goes out of the screen or
becomes invisible. This is useful for enabling/disabling certain resource or network-consuming operations that are part of the ad
loading process.
Alias
string property
1.0
Alias of the placement.
RefreshInterval
string property
1.0
Refresh interval of the placement.
GroupId
int? property
1.0
Group ID of the placement. Two placements can be identified as being part of the same page by setting the same group id to each of
them.
NetworkId
int? property
1.0
Network ID of the placement.
SubnetworkId
int? property
1.0
Sub-network ID of the placement.
Animation
AdAnimation?
property
1.0
Animation used for transitioning between ads.
Domain
string property
1.0
The ad server domain.
ExtraKeyValueParams
Dictionary
<string,List<string
>> property
1.0
Enables the developer to add custom key-value parameters that
should be passed to the server when requesting an ad.
Load()
method
1.0
Starts loading the ads.
AddKeyValueParameter(String
key, params
String[] values)
method
1.0
Adds extra key value parameters to the add configuration.
2012-12-18
Parameters:
• key: The key of the parameter.
• values: One or more value parameters.
Page 199 of 216
Windows 8 Class: AdtechBannerControl
About the class
• Name: AdtechBannerControl
• Since: 1.0
Description:
This is a view class that provides an MRAID compliant ad container. It represents the
primary gateway between the ADTECH SDK and the user of the SDK (application developer).
More than one such view can be used at a time and they are independent from one
another.
You can register to multiple banner life cycle events through the described public interface.
Public Interface
Member
Type
Since
Description
AdtechBannerControl()
constructor
1.0
Constructs a new ad banner.
OnAdSuspend
event
1.0
Occurs when the application should suspend its job, because
the advertisement has been expanded and covers the whole
screen. This might be useful in games, or video play-back
apps.
OnAdResume
event
1.0
This event occurs when the ad has been resumed in the default state.
2012-12-18
Page 200 of 216
Windows 8 Class: AdtechInterstitialControl
About the class
• Name: AdtechInterstitialControl
• Since: 1.0
Description:
This is a full-screen MRAID ad container. Each interstitial ad should be added by creating one instance of this class.
Interstitial ads are usually used when a time-intensive operation is in process, like
loading a game. The user will be engaged in the ad while waiting for the process to
finish.
Public Interface
Member
Type
Since
Description
AdtechInterstitialControl()
constructor
1.0
Constructs a new interstitial control.
OnAdDismiss
event
1.0
Occurs when the interstitial timer expires and the user should
dismiss/hide the view.
2012-12-18
Page 201 of 216
Windows 8 Enums
About the enum
• Name: AdAnimation
• Since: 1.0
Description:
Defines the possible animations for the Windows 8 SDK ad transitions.
Public Interface
2012-12-18
Name
Since
Description
NONE
1.0
No animation used for switching the ads.
TOP_TO_BOTTOM
1.0
The ads are going to be switched by animating the new incoming ads from the top to the bottom of the container.
LEFT_TO_RIGHT
1.0
The ads are going to be switched by animating the new incoming ads from the left to the right of the container.
RIGHT_TO_LEFT
1.0
The ads are going to be switched by animating the new incoming ads from the right to the left of the container.
FLIP_FROM_RIGHT
1.0
New ads are going to be flipped in from the right side of the
FLIP_FROM_LEFT
1.0
New ads are going to be flipped in from the left side of the
Page 202 of 216
2.11
Windows Store Submission Guidelines (Windows 8)
In this section
Topic
Page
Application Policies for the Windows 8 Store .................................................... 204
2012-12-18
Page 203 of 216
Application Policies for the Windows 8 Store
Introduction
This topic provides information regarding the Windows store submission process with
regard to the ad content within your application.
Application policies
As you probably know, the Windows Store submission process validates and approves
your app before it is available on the market. The submission process has some rules
regarding the:
•
•
•
•
•
•
•
•
Upload
Preprocessing
Security tests
Technical compliance tests
Content compliance
Release
Signing and publishing
Certification report
With regard to application and ad content, there are some considerations:
• “Windows Store apps can display ads but are more than just ads or websites”
• “Your app must not display only ads – If your app includes or displays ads, it
must provide additional functionality beyond the ads.”
• “Ads in your apps must comply with our content policies – Our content policies are
described in Section 5. Windows Store apps are appropriate for a global audience
http://msdn.microsoft.com/en-us/library/windows/apps/hh694083.aspx#acr_5_0.”
• “Ads must not execute program code that didn’t come from the ad provider”
All the rules can be found in the Windows Store Dev Center
http://msdn.microsoft.com/en-us/library/windows/apps/br230835.aspx.
2012-12-18
Page 204 of 216
2.12
ADTECH Mobile SDK Limitations
In this chapter
Topic
Page
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
2012-12-18
Page 205 of 216
Platform Specific Mobile SDK Limitations
Restrictions
iOS
The following general limitations apply for the ADTECH Mobile SDK.
Limitation
Description
Flash
Flash can not be played.
Video playing
Inline video playing and video auto-play is available only in
iOS 4.0 and above for the banner and interstitial ads.
Carrier name detection is available only in iOS 4.0 and
above.
No VAST companions
Only linear and non-linear ads described by the VAST
specification are supported at the current time (no support for companion ads yet).
Image non-linears
Only image non-linears are currently supported.
Interstitial ads are presented in
portrait orientation for releases
before and including 2.2.4.
For releases before and including 2.2.4, only the portrait
orientation is allowed for interstitial ads.
Ads must not call MRAID or
ORMMA methods that reach the
Objective-C native code before
the ad is done rendering.
Some calls to ORMMA or MRAID reach the Objective-C
native code. Some of them are:
•
•
•
•
•
expand
resize
open
playVideo
registering for device native features (location, heading, orientation, shake events).
The ad must not call these methods before the ad is done
rendering, i.e. before the ready event is triggered. Failing
to do so will stop the rendering of the ad.
Calls to get values or to set properties, like expand or orientation properties, are allowed.
Android
2012-12-18
Limitation
Description
Inline video play
Inline video playing is only available for Android 3.1 and
above but does not work consistently.
No VAST companions
Only linear and non-linear ads described by the VAST
specification are supported at the current time (no support for companion ads yet).
Image non-linears
Only image non-linears are currently supported.
Page 206 of 216
Limitation
Description
Hardware accelerated rendering
is disabled for the AdtechBannerView and AdtechInterstitialView.
Webview’s background is white instead of transparent on
Android 3.0 and above if application is built with hardwareAccelerated="true" in the Android Manifest.
This is a known issue of the Android OS. See more regarding this issue here
http://code.google.com/p/android/issues/detail?id=14749
.
Furthermore, the video playback and hardware rendering
done in webviews is totally out of the SDK’s control, and in
some cases there seem to be memory issues and the application crashes without any error notifications whatsoever (neither Exception in code which could be handled,
nor visible error dialog presented to application users).
This is considered as unacceptable, because one of the
main requirements of the SDK is to not cause crashes in
the host application. The SDK should provide added value
and not interfere with user experience.
Thus since this behavior can not be controlled, neither can
the issue with background transparency be fixed, hardware rendering is programatically disabled at runtime.
Even if the entire application is set to use hardware rendering, the AdtechBannerView's webview will use software rendering.
Windows 8
2012-12-18
Testing on Emulators is not advised.
Ad delivery is based on the user agent of the device. The
emulator is not supported because of the lack of correct
user agent information.
Limitation
Description
The WebView showing the ad
can be manipulated.
The WebView that displays the ad can be manipulated in
the following ways: pinch (zoom in or zoom out), or
moved around (translation). This is a limitation of the
WebView control from the Windows 8 SDK.
The WebView has top-most
Z-index.
Because of the way the WebView is implemented in the
Windows 8 SDK, it will have the top-most Z-index, meaning that nothing can be positioned above it. For example,
if we were to hide the ad by putting a button to cover it,
the WebView (AdBannerControl) will be still be displayed and it will hide instead the button. This is a known
“airspace” issue (see MSDN Forums
http://social.msdn.microsoft.com/Forums/en-US/winapps
withcsharp/thread/23a235a2-b0a3-4161-bc74-c42289c61264)
Close button overlay not transparent
This is a limitation of the WebView control, which cannot
be made transparent. Thus, if using a non-custom close
button (that is, the one provided by the SDK), the close
button circle will be surrounded by a white-background
rectangle.
Page 207 of 216
MRAID 1.0 SDK Limitations
iOS
Feature
Limitation
Inline video play & Available only from iOS 4.0 and above
video auto play
Android
Windows 8
2012-12-18
Available only from iOS 4.0 and above
Feature
Limitation
Inline video play
Not supported
No known issues at the moment.
Page 208 of 216
MRAID 2.0 SDK Limitations
iOS
Feature
Limitation
playVideo
The following parameters are not supported:
• audio = muted (will be ignored because there is no support for this
in iOS)
Prior to iOS 5.0 the video starts being played back automatically, no
matter the value of the autoplay parameter. This is an OS limitation.
The show controls parameter might be forced by the SDK to YES in the
following cases:
• If loop playback is requested, the SDK forces the controls to be
shown. So the user has an easy way of stopping the loop.
• If autoplay is set to NO, then the SDK forces the controls to be
shown. Otherwise the users might not know that interaction is
needed on their side and might be confused about the blank screen
not doing anything.
• Even if autoplay is set to NO, if inline playback is requested, the autoplay will be forced to YES and the show controls value will not be
changed.
storePicture
When using the option to take a screenshot (the URL is
mraid://screenshot) the UI and the app will be blocked and the user can not interact with it while the screenshot is being taken. This can
last up to several seconds.
createCalendarEvent
The status parameter from the W3C calendar specification is not supported (see here).
The exceptionDates parameter from the W3C calendar specification is
not supported (see here
http://www.w3.org/TR/calendar-api/#widl-CalendarRepeatRule-excepti
onDates).
The weeksInMonth parameter from the W3C calendar specification is
not supported (see here
http://www.w3.org/TR/calendar-api/#widl-CalendarRepeatRule-weeksI
nMonth).
The SDK supports major date formats for the dates specified when calling this method, but not all the possible Internet date formats are supported.
The supported formats are:
•
•
•
•
2012-12-18
yyyy-MM-ddTHH:mm:ssZZZ
yyyy-MM-ddTHH:mm:ss.SSSZZZ
yyyy-MM-ddTHH:mmZZZ
yyyy-MM-ddTHH:mm:ss.
Page 209 of 216
Feature
Limitation
getCurrentPosition, getDefaultPosition,
getMaxSize
In some rare cases, the value returned to the ad when calling getCurrentPosition might not be up-to-date.
The scenario is like this:
• A rich media banner ad is shown on the view of a view controller
allowing multiple orientations.
• The ad is expanded and while expanded, the interface orientation is
changed.
• The expanded ad is closed at this point.
As a result, the currentPosition the ad will get from the SDK is the old
value before the expansion took place. Changing the interface orientation at this point will correctly update the currentPosition.
The same applies for defaultPosition and getMaxSize.
Linking to external
apps
The SDK can allow access for the ad to other applications through URLs
that are formed in a certain way, usually through custom protocol
schemes.
The URLs need to conform to the Apple iOS documentation (see here)
Android
Feature
Limitation
playAudio
The following parameters will have no effect (the OS does not support
them):
• autoplay: the audio will always play immediately
• controls: if not in inline mode, the controls will always be visible
• loop: the audio will only be played once
• stopStyle: in full screen mode, depending on the media player implementation, the media player will exit on some devices and will
remain displayed on others
playVideo
• inline: the video will always be played in fullscreen mode
• startStyle: the video will always be played in fullscreen mode
• if autoplay is set to true, then the SDK forces the controls to be
shown; otherwise the users might not know that interaction is
needed on their side and might be confused about a the blank
screen not doing anything
2012-12-18
Video playback
does not work
properly on Android 4.0
The webview does not provide a VideoView for video playback, instead
it starts playing the audio part of the video.
setOrientationProperties
Orientation properties are not supported by the SDK.
The behavior will always be as if allowOrientationChange was set to
TRUE.
Page 210 of 216
Feature
Limitation
createCalendarEvent
The reminder parameter from the W3C calendar specification is not
supported (see
http://www.w3.org/TR/calendar-api/#widl-CalendarEvent-reminder ).
The exceptionDates parameter from the W3C calendar specification is
not supported (see
http://www.w3.org/TR/calendar-api/#widl-CalendarRepeatRule-excepti
onDates).
Supported date formats are:
•
•
•
•
•
yyyy-MM-dd
yyyy-MM-dd' 'HH:mmZ
yyyy-MM-dd'T'HH:mmZ
yyyy-MM-dd'T'HH:mm:ss.SSSZ
yyyy-MM-dd'T'HH:mm:ssZ
Some devices might not support daysInYear/weeksInYear/weeksInMonth values for recurrences.
2012-12-18
Page 211 of 216
ORMMA Level 2 SDK Limitations
iOS
Feature
Limitation
playVideo
Only the stopStyle: "exit" is supported on iOS 4.3. iOS version 5.0 and
higher support allows "normal"
playAudio
When playing inline, the audio will play in the background and the user
will have no control over it. When inline, the audio will start and end
automatically.
If inline param is set to YES, then the following params are overwritten
by the SDK:
•
•
•
•
•
autoplay = YES
loop = NO
controls = NO
stopStyle = exit
startStyle - param is ignored
Prior to iOS 5.0 the audio starts being played back automatically, no
matter the value of the autoplay parameter. This is an OS limitation.
The same behavior related to the show controls parameter applies for
audio as for video.
Android
tilt
available only from iOS 4.0 and above
setExpandProperties
The following properties are not supported:
Feature
Limitation
playAudio
The following parameters will have no effect (the OS does not support
them):
• backgroundOpacity: will be ignored and always set by the SDK to
1.0
• autoplay: the audio will always play immediately
• controls: if not in inline mode, the controls will always be visible
• loop: the audio will only be played once
• stopStyle: in full screen mode, depending on the media player implementation, the media player will exit on some devices and will
remain displayed on others
playVideo
• inline: the video will always be played in fullscreen mode
• startStyle: the video will always be played in fullscreen mode
• If autoplay is set to true, then the SDK forces the controls to be
shown; otherwise the users might not know that interaction is
needed on their side and might be confused about a the blank
screen not doing anything.
setExpandProperties
2012-12-18
The following properties are not supported:
• lockOrientation: will be ignored and always set by the SDK to FALSE.
Page 212 of 216
Caching and Offline Display SDK Limitations
iOS
Android
2012-12-18
Feature
Limitation
Caching is not supported for
iPhone OS 3.1 and iOS 3.2.
Caching of creatives is available starting only iOS version
4.0.
Video & audio assets are not
cached
For performance reasons the video and audio assets are
not cached by the ADTECH Mobile SDK even if the ad
marked as cacheable lists the video and audio in the assets
manifest. Because of this when the ad is shown offline the
video or audio will be missing for the ad content.
3rd party mediated ads are not
cached
The ADTECH Mobile SDK does not cache 3rd party mediated
ads.
Feature
Limitation
Video & audio assets are not
cached
For performance reasons the video and audio assets are
not cached by the ADTECH Mobile SDK even if the ad
marked as cacheable lists the video and audio in the assets
manifest. Because of this when the ad is shown offline the
video or audio will be missing for the ad content.
3rd party mediated ads are not
cached
The ADTECH Mobile SDK does not cache 3rd party mediated
ads.
Caching does not work on devices with HTC’s Sense UI 3.0
On devices running Android versions lower than 3.0 caching is implemented with the help of an embedded web
server which acts as a proxy host for the assets of the
ADTECH ads. Since Sense UI 3.0 the Android system does
not use the local proxy web server anymore.
Page 213 of 216
VAST SDK Limitations
iOS
Limitation
Description
Autoplay of content is disabled
Using the shouldAutoplay property or the setShouldAutoplay method on the ATMoviePlayerController has no
effect. Autoplay is disabled.
Only the first linear ad from a
VAST document is considered
If the VAST document received has more than one linear
creative, only the first one is used
Wrapper content are merged
with the first creative found
All the data gathered from wrapper redirections will be
merged with the first encountered creative in the inLine
response
If the movie type is stream
based and the mid-roll start
time is not specified as a VAST
extension, the mid-roll will be
skipped.
For movies that are stream based, the content length
might be unknown (or unreliable). If the start time for a
mid-roll is not specified as an extension in the VAST document, the player will not know when to present the
mid-roll and will skip it. This event will be logged to the
console.
based and of undetermined
length (live streaming), the
post-roll won't be shown
For movies that are stream based and don't have a determined length there is no possibility to present the post-roll
because the content won't end playing. The user has to
stop playback at some point.
The mute-unmute event is not
triggered by the hardware mute
switch
Using the hardware mute-unmute switch won't trigger the
corresponding tracking events because the application is
not notified of the change in the switch's state.
The mute-unmute events are triggered by lowering the
volume under a hear-able threshold or raising it above
that.
For video ads of very short
length, it might be that not all
tracking event related to playback progress will be triggered.
If the presented video ads are very short (maybe less than
2 seconds), it might happen that the SDK is not able to distinguish playback progress events that happen very close
another after another (first quartile, mid point, third quartile, complete).
Only non-linear creatives with
type StaticResource and an image mime-type are supported.
VAST specifies the following types for non-linear creatives:
• HTML
• iFrame
• StaticResource, with mime-type (video, image, text,
etc)
Only Static Resources with the mime-type of an image are
supported currently.
2012-12-18
Page 214 of 216
Android
Limitation
Description
Autoplay of content is disabled
Using the shouldAutoplay property or the setShouldAutoplay method on the ATMoviePlayerController has no
effect. Autoplay is disabled.
Only the first linear ad from a
VAST document is considered
If the VAST document received has more than one linear
creative, only the first one is used
Wrapper content are merged
with the first creative found
All the data gathered from wrapper redirections will be
merged with the first encountered creative in the inLine
response
based and the mid-roll start
time is not specified as a VAST
extension, the mid-roll will be
skipped.
For movies that are stream based and don't have a determined length there is no possibility to present the post-roll
because the content won't end playing. The user has to
stop playback at some point.
The mute-unmute event is not
triggered by the hardware mute
switch
Using the hardware mute-unmute switch won't trigger the
corresponding tracking events because the application is
not notified of the change in the switch's state.
Mute-Unmute is disabled.
For video ads of very short
length, it might be that not all
tracking event related to playback progress will be triggered.
If the presented video ads are very short (maybe less than
2 seconds), it might happen that the SDK is not able to distinguish playback progress events that happen very close
another after another (first quartile, mid point, third quartile, complete).
Only non-linear creatives with
type StaticResource and an image mime-type are supported.
VAST specifies the following types for non-linear creatives:
• HTML
• iFrame
• StaticResource, with mime-type (video, image, text,
etc)
Only Static Resources with the mime-type of an image are
supported currently.
Some video resources can not
be played appropriately on
some devices.
i.e: Certain devices like the Samsung Galaxy S or the HTC
Wildfire S fail to load certain videos or they throw errors
while playing the video.
This is a limitation caused by the native android VideoView
which does not handle video playback correctly on some
devices. The most common errors that are logged by the
video player are: android.media.MediaPlayer
http://developer.android.com/reference/android/media/M
ediaPlayer.html’s MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
and MEDIA_ERROR_UNKNOWN.
2012-12-18
Page 215 of 216
Chapter 3
Glossary
ADTECH Mobile
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. The keyword, key value and alias
features are used to pass manufacturer, device, carrier, operating system and size information. The Mobile Ad Server replaces the actual device screen size with a size
category so that the banner will be displayed correctly. Special mobile reports are
available.
Android
Android is an operating system by Google, and runs on many mobile devices It is written in Java. It is a platform used by many apps and is supported by ADTECH Mobile.
App
Banners can be delivered to mobile websites and mobile applications (apps). As they
need to be treated differently than mobile websites, there is an SDK available for app
developers that explains how to implement banners in apps.
iOS
iOS is an operating system that runs on Apple devices. It is written in Objective-C. It is
a platform used by many apps and is supported by ADTECH Mobile.
Mediation
A mediation partner helps to fill remnant inventory with ads as and when available.
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.
Refresh Interval
In contrast to a mobile website, users will often stay on only one page when using
mobile apps. In that case, in order to serve more than one impression per user session, you can define a refresh interval for the placement that you implemented in your
app. The defined value determines the time period which will elapse, before a new ad
is requested.
SDK
The purpose of the SDK (Software Development Kit) is to provide the app developers
with installation instructions and code samples to help them implement placements
into mobile apps. Since different platforms (operating systems) are used, different
SDKs for each platform are required.
2012-12-18
Page 216 of 216

ADTECH Mobile for App Developers

Transcription

Similar documents

J.P. Uniac mobile!

Maxx Money Kids` Club

Able2Extract Mobile on iOS

Mediafin - IAB Community

vTuner Internet Radio Rapid Prototyping SDK USB

BMC Case History - Mobiloil

Able2Extract mobile Quick Start Guide

The Joys and Sorrows of Teaching and Developing Apps for Mobile

Customer Service Measurements - PetMeds ® Investor Relations

Advertising to run in the program for