Integration guide for Android VAST SDK version 1.1.xIntroductionDeployment packageSystem requirementsAdServer prerequisitesBuild path and imported classesSetup the Phantom objectRequest for single adRequest for multiple adsPlay an adGuidelines to deliver synchronised companion display adsTracking eventsOpen destination url on click

IntroductionThe following documentation is a guide for integrating the Android VAST SDK library in Android mobile applications in order to make theseapplication capable of requesting and processing advertising content from VAST 2.0 supported ad servers* (some functionalities may not becompatible).The documentation assumes that the user has good knowledge on ADT and Java.

The Android VAST SDK library only responsible for requesting for ads and returning a list of specific objects ( ) with the certainAdResponseproperties of an ad (media file, trackers, etc). The library has no responsibility to assure a good or any playback of advertising content however itwill provide all the necessary information for the application in order to present the desirable advertising experience.

The library will requests ads on demand. This means that the library has no knowledge on formats as preroll, midroll or postroll.

Deployment packageBefore starting the integration make sure that the deployment package is the latest or the desired one. The deployment packages for version 1.1.xwill contain the following:

- the library filephantomAdswizz_1.1.x.jar jarphantomAdswizz_1.1.x_api_doc.zip - the api documentation

System requirementsAndroid application developed for OS version 2.3 or newer

AdServer prerequisitesIn order to be able to use the library the appropriate ad-server information needs to be configured on the dedicated ad-server andmandatoryused to build up the ad-request( ).swfIndexThis information include:

ad-server host ( ), e.g.. server deliveryengine.yourdomain.adswizz.com zone id information ( ),e.g. numberOfAdszoneId [{z:zoneId, n:numberofAds}, {z:zoneId, n: }, ...]zone alias information e.g( ). zone_alias [{za:zoneAliasReference, n:numberofAds}, {za:zoneAliasReference, n:numberOfAds}, ...];

Note: Zone alias and zone id are exclusive(). If both parameters are provided will overwrite the zone aliaszoneId .For the parameters please consult the further documentation related to the protocol.optional swfIndex

Build path and imported classesIn order to use the library for requesting ads from adswizz adservers it has to be added to the project's Build Path.

After the library is in the build path the import the following classes has to be imported into the source code of the application where the requestsand / or trackings will take place.

//a class with static event names to be triggered during the ad playbackimport com.adswizz.tracker.AdEvent;

//a class representing a value object with all the information needed to make an adrequestimport com.adswizz.phantom.AdRequestObjectInterface;

//class representing an ad reponse, an object created based on the VAST xml the serverrespond to an ad request. The object will contain all the necessary information inorder to play and track an adimport com.adswizz.phantom.AdResponse;

//the library api classimport com.adswizz.phantom.Phantom;

Setup the Phantom objectIn order to use the SDK's api a Phantom object has to be initialized as follows. Due to the fact that the application sessionId is handled byPhantom and it's unique per Phantom instance, do NOT reinitialise Phantom during the application lifetime.

phantom = new Phantom();

Request for single adIn order to make an ad-request from your application use phantom.requestAd( AdRequestObjectInterface requestObject, final

) method. AdRequestHandlerInterface requestHandler, Context contextfinal finaladRequestHandlerInterfaceInstance object has two methods:

onResponseError: handles erroneous requestonResponseReady: handles successful requests

The adResponse object in case of a successful ad-request will be passed as the argument of the method. Se exampleonResponseReadybelow:

private AdRequestHandlerInterface ahi = new AdRequestHandlerInterface(){ @Override public void onResponseError(PhantomError error) { playMainContent(); // play the publisher content }

@Override public void onResponseReady(AdResponse requestResponse) { adResponse = requestResponse; playAd(); // start playing the ads }};

aoi = new AdRequestObjectInterface();aoi.timeout = 3000; //the timeout in milliseconds for an ad request to respondaoi.zoneId = 12345 //zone id;aoi.server="yourdomain.adswizz.com";aoi.referrer="http://mytest";aoi.zone_alias = [{za:zoneAliasReference, n:numberofAds}, {za:zoneAliasReference,n:numberOfAds}, ...];aoi.tagsArray="var1%3Dval1%26var2%3Dval2"; //must be url encoded

//make the requesttry { phantom.requestAd(aoi, ahi, this); }}catch ...

The method is documented in the api documentation of the library delivered in the deployment package.phantom.requestAd()

Request for multiple adsIn order to make an ad-request from your application use phantom.requestAd(final AdRequestObjectInterface requestObject,

) method.final AdMultiRequestHandlerInterface requestHandler, final Context contextadRequestHandlerInterfaceInstance object has two methods:

onResponseError: handles erroneous requestonMultiResponseReady handles successful requests:

The list of adResponse objects in case of a successful ad-request will be passed as the argument of the method. SeonMultiResponseReadyexample below

private AdMultiRequestHandlerInterface amhi = new AdMultiRequestHandlerInterface(){ @Override public void onResponseError(PhantomError error) { Log.e(TAG, "onResponseError " + error.toString()); playMainContent(); } @Override public void onMultiResponseReady(ArrayList requestMultiResponse) { Log.d(TAG, "onMultiResponseReady "); adArray = requestMultiResponse; playMultipleAds(); }};...

aoi = new AdRequestObjectInterface();aoi.timeout = 3000; //the timeout in milliseconds for an ad request to respondaoi.zoneId = [{z:zoneId, n:numberofAds}, {z:zoneId, n:numberOfAds}, ...];aoi.server="yourdomain.adswizz.com";aoi.referrer="http://mytest";aoi.zone_alias = [{za:zoneAliasReference, n:numberofAds}, {za:zoneAliasReference,n:numberOfAds}, ...];aoi.tagsArray="var1%3Dval1%26var2%3Dval2"; //must be url encoded

//make the requesttry { phantom.requestAd(aoi, amhi, this); }}catch ...

The method is documented in the api documentation of the library delivered in the deployment package.phantom.requestAd()

Play an adIn order to get the resource url of the media file from an ad use the following code

String mediaUrl = ad.mediaFile.source;

Guidelines to deliver synchronised companion display adsIn order to have a companion ad displayed a specific information, context has to be sent to the ad-server in the request of the ad.

The context is a property of the AdResponse.

If the context could has no value or is an empty string it means that the media file is not part of a companion campaign therefor there is no displaycompanion handled with it.

In order to present the companion ad a has to be opened with the following url:WebView

http://your_domain.adswizz.com/www/delivery/afr.php?zone_alias=displayzonealias&context=context&tags=tagsArrayIfAny&cb=randomNumber

Tracking eventsTracking events on ad playback is done also by the instance of the using event types defined in The following type ifAdResponse AdEvent.events should be used:

tracking impression: AdEvent.AD_IMPRESSIONtracking ad start: AdEvent.AD_VIDEO_STARTtracking ad first quartile: AdEvent.AD_VIDEO_FIRST_QUARTILEtracking ad reaches 50%: AdEvent.AD_VIDEO_MID_POINTtracking ad reaches 75%: AdEvent.AD_VIDEO_THIRD_QUARTILEtracking ad completed: AdEvent.AD_VIDEO_COMPLETEtracking user clicks on the video ad: AdEvent.AD_CLICKTRACKING

Use the following code to track an event from the list above

AdResponse ad = adArray.get(index); //the index can be iterated or selected by choicephantom.trackEvent(ad, AdEvent.AD_IMPRESSION);

Open destination url on clickIn order to open a destination url of an ad the following source can be considered

AdResponse ad = adArray.get(index); String destinationUrl = ad.clickThru;

Intent intent = new Intent("android.intent.action.VIEW", destinationUrl);startActivity(intent); //start the right app to handle the click url

Integration guide for Android VAST SDK version 1.1.x