VservAndroid

SDK
v2.2

Version2.2.2

Contents

Introduction
Prerequisites
DownloadtheSDK
SettingupyourAndroidProject
IntegratingtheVservSDKlibrary
Updatingyourproject.propertiesfile
GooglePlayServicesSDK
RequestingVservAds
RequestingInterstitials
ManagedInterstitialsusingdisplayAd()
ManagedOverlayAdsusingdisplayAd()
RequestingforaparticularorientationindisplayAd()
InterstitialCaching
LaunchandExitAdssamples
UnmanagedInterstitialsusinggetAd()&overlay()
RequestingBannerAds
ManagedBannerAdsusingrenderAd()
UnmanagedBannersusinggetAd()&show()
TestingIntegration
AddingTestDevices
UsingtheTestZones
VservManagerOptions
AppendixA:ProGuardSetting
AppendixB:OptionalPermissions

Version2.2.2

Introduction
TheVserv.mobiAndroidSDKisdesignedtohelpyouintegrateVservAdsinyourapplicationandfasttrackyour
waytomonetizingyourAndroidapplications.
Prerequisites
Beforeyoubegin,weneedtomakesureofafewthings:

1. YouhaveaVserv.mobiDeveloperAccount.Ifyouhaveone,gotoStep2.Ifyoudonot,signupatour
DeveloperPortal.
2. NotedownyourZoneID.ThiswillberequiredlateronwhenyouusetheAndroidSDKtorequestAds.
ThedefaultZoneIDwillbeavailableinyourwelcomeemailoryoucouldvisit
https://admin.vserv.mobi/admin/affiliatezones.phptogetalistofallyourzones.
3. YourAndroidprojectshouldbecompiledagainstAPILevel18.
Note:PleasedonottargetAPIlevel19asthereareafewknownissues.
4. YourADTversionmustbe22andabove.
DownloadtheSDK
ThefirststeptointegratingVservSDKinyourAndroidapplicationistodownloadourSDKpackage.TheSDK
packageisavailablefromhere.

WesuggestthatyouunziptheSDKZipfilethatyoujustdownloadedintoatemporaryfolder.Assumingthatthe
folderis[VSERV_SDK_FOLDER],youwillseethefollowingcontents:

AndroidV2SDKLibrary/ ThisistheVservSDK,itspackagedasan
AndroidLibraryProject.
AndroidV2SampleApp/ SampleAndroidprojectsourcecodethat
demonstratesVservSDKintegration.
SettingupyourAndroidProject
WeneedtocompleteafewstepsfirsttoensurethatyourAndroidProjectissetupwiththeVservSDK.This
involvesthefollowing:
IntegratingtheVservSDKlibrary
YouneedtoimporttheVservAndroidLibraryprojectintoyourworkspace[File>Import].

Version2.2.2

NextyouneedtoaddtheVservlibrarytoyourproject.Forthisyouneedtorightclickonyourprojectandgoto
theAndroidtab.UndertheLibrarysectionclickAddandselectAndroidV2SDKLibrary.
Updatingyourproject.propertiesfile
SincetheVservAndroidSDKisalibraryprojectyouneedtoaddthefollowingtoyourproject.propertiesfile.

manifestmerger.enabled=true

Mandatorypermissionsarealreadyapartofthelibraryproject.Youmayprovideadditionalpermissionstothe
VservSDKsothatitcanservericher,moretargetedadstotheenduser.
ThesepermissionsareprovidedinAppendixB.
GooglePlayServicesSDK
TheVservSDKneedstheGooglePlaySDKtofunction.YoucanreferthistutorialonhowtoaddtheGoogle
PlayServicesSDKtoyourproject.

Important:IfyourprojectoralibraryyouareusingalreadymakesuseofGooglePlayServicesorGoogleAds
pleaseremovethefollowinglinefromtheVservLibrarysAndroidManifest.

<!RemovethisifyourprojectoralibraryyouareusingalreadymakesuseofGooglePlayServicesor
GoogleAds>
<metadata
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version"/>

RequestingVservAds
TheVserv.mobiSDKprovidesyouwithvariousmechanismstorequestforAdsinyourAndroidapplication.The
SDKprovidesbothsimplefullymanagedAdrequestmethodsandalsotheget&showAdmethodstoenable
prefetchingofads.
RequestingInterstitials
ManagedInterstitialsusingdisplayAd()
TorequestaninterstitialyouneedtocallthedisplayAd()method.Hereisanexample

VservManagermanager=VservManager.getInstance(context)
manager.setShowAt(AdPosition.IN)

Version2.2.2

manager.displayAd(YOUR_ZONE_ID)

displayAd()isapartoftheVservManager(mobi.vserv.android.ads)whichneedtobeinitializedbefore
requestingforanAd.
ManagedOverlayAdsusingdisplayAd()
TheDisplayAd()methodbydefaultdisplaysaninterstitialbutcanbeusedtodisplayanOverlayadforamore
nativeexperience.TorequestanOverlayadyouneedtopasstheAdTypetotheOverloadeddisplayAd()
method.

VservManagermanager=VservManager.getInstance(context)
manager.setShowAt(AdPosition.IN)
manager.displayAd(YOUR_ZONE_ID,AdType.OVERLAY)

YoucanpasseitherAdType.OVERLAY&AdType.INTERSTITIALtodisplayAd().
PleasenoteyouwillhavetohandlerotationoftheActivityincaseofOVERLAYAds.IfyourActivityrestarts,the
Adwillbeforcefullyclosed.
RequestingforaparticularorientationindisplayAd()
YoucanrequestforaninterstitialinaparticularorientationbypassinganAdOrientationparameterto
displayAd()asshown.

VservManagermanager=VservManager.getInstance(context)
manager.setShowAt(AdPosition.IN)
manager.displayAd(YOUR_ZONE_ID,AdOrientation.LANDSCAPE)

AdorientationwilleitherbeAdOrientation.LANDSCAPEorAdOrientation.PORTRAIT

ThesetShowAt()isanoptionalmethodwhichletsVservknowwhereyouareplacingtheinterstitial.The
possibleparametersareAdPosition.START/AdPosition.IN/AdPosition.END.ThesevalueswillbeusedforAd
TargetingandAnalyticsanditisadvisablethatyoupasstheparameter.
InterstitialCaching
BydefaulttheAndroidSDKprecachesinterstitials.Youcancontrolthisbehaviourbyusingthe
setCacheNextAd()method.Themethodtakesabooleanasaparameter.

VservManagermanager=VservManager.getInstance(context)
manager.setCacheNextAd(true)
LaunchandExitAdssamples
ThefollowingcodeprovidesanexampleonhowtorequestanInterstitialatlaunch.

Version2.2.2

@Override
protectedvoidonCreate(BundlesavedInstanceState){
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

//InitializationCodeandEventHandlers
VservManagermanager=VservManager.getInstance(context)

manager.setShowAt(AdPosition.START) //"start"indicatesalaunchAd
manager.displayAd(YOUR_ZONE_ID)//PassyourZoneID
}

Ifyouwanttorequestaninterstitialonexityoucanusethefollowingexample:

@Override
publicvoidfinish(){
//Yourcleanupcode
manager.setShowAt(AdPosition.END)
manager.displayAd(YOUR_ZONE_ID)
//Notewearenotcallingsuper()here,Youshouldcallitin
//onActivityResult()asshowninthesnippetbelow.
}

VservinterstitialslaunchesindependentActivitieswhichreturnstheshowAtparameter,thusyoucanimplement
theonActivityResultmethodinyourActivitytogetthesame.Ifyouarecallingforinterstitialsatlaunchandexit
thisallowsyourActivitytoknowwhichadwasrequested.Inadditionalyoucanalsocalltherelease()method
toforcetheSDKtoreleaseitsresourcesforthatsession.

if(requestCode==VservManager.REQUEST_CODE){
if(intent!=null){
if(intent.hasExtra("showAt")
&&intent.getStringExtra("showAt").equalsIgnoreCase("end")){
VservManager.getInstance(this).release(this)
super.finish()
}
}else{
super.finish()
}
}
UnmanagedInterstitialsusinggetAd()&overlay()
ThismechanismgivesyouthemaximumcontroloverAdretrieval.getAd()allowsyoutoprefetchmultipleAds.
Ittakesintwoparameters,aZoneIDandanAdLoadCallBacklistener.

getAd(StringzoneId,AdLoadCallbackmyAdLoadCallbackListener)
InadditionyoucanalsorequestforaparticularorientationbypassinganAdOrientationparameter.

Version2.2.2

getAd(StringzoneId,AdOrientationadOrientation,AdLoadCallbackmyAdLoadCallbackListener)

TheAdLoadCallback(mobi.vserv.android.appwrapper.AdLoadCallback)interfaceprovidescallsbackstoget
thestatusofyoureaRequest.Ithasthefollowingcallbacks:

onLoadSuccess(VservAdadObj)

ThiscallbackmethodisinvokedwhenanAdhasbeensuccessfullyretrieved.Youcanuseto
eitherstoreitforlateruseordisplayitimmediatelyviatheshow()

onLoadFailure()

ThiscallbackmethodisinvokedwhentherewasanerrorinretrievingtheAdfromtheVservAd
Network.

onNoFill()

ThiscallbackmethodisinvokedwhentherewasnoAdavailable.

AsampleimplementationofthegetAd()methodwiththecallbackisshownbelow.Thissampleusedthe
overlay()methodtoshowtheinterstitialimmediately.

manager.getAd(myZoneID,newAdLoadCallback(){
@Override
publicvoidonLoadSuccess(VservAdadObj){
this.adObject=adObj
adObject.overlay(context)
}
@Override
publicvoidonLoadFailure(){
Log.d(tag,FailedingettingAd)
}
@Override
publicvoidonNoFill(){
Log.d(tag,"NoAdFound")
}
})

AsindisplayAd()youcanpassanAdTypetooverlay()sothatyoucandisplayyourcachedAdineitheran
interstitialformatoranoverlayformatasshownbelow:

adObj.overlay(context,AdType.OVERLAY)

IfyouneedtogettheZoneIdforwhichanadwasreturnedyoucancalltheadObject.getZoneId()method.

Version2.2.2

RequestingBannerAds
ManagedBannerAdsusingrenderAd()
YoucanrequestforBannerAdswhichautorefreshautomaticallyinaspecificViewusingrenderAd().The
signatureforthemethodisshownbelow:

VservControllerrenderAd(StringzoneId,ViewGroupviewGroup)

TheViewGroupisacontainerinyourActivitylayoutwhereyouwanttheAdtobedisplayed.Ideallysetthe
ViewGroupsheightandwidthtowrapcontent,youmayadditionallyalignittothetoporbottomofthescreen.
Note:Ifnonemptycontainerispassed,therenderAd()methodwillremoveallthechildrenofthegroup.

TherenderAd()methodalsoprovidesareturnobject,whichisaninstanceof
mobi.vserv.android.appwrapper.VservControllerclass.TheVservControllerinstancecanbeusedtoadjustthe
refreshintervalandalsochangetheZoneID,ifyouwantto.

ThemethodsontheVservControllerobjectaregivenbelow:

setRefresh(intrefreshInterval)

ThismethodcanbeusedtosetaspecificrefreshtimefortheAd.Notetheminimumrefreshtimeis30
seconds.Alsosettingtherefreshtimeto0willdisablerefresh.Thedefaultrefreshtimeis60seconds.

setZone(StringZoneID)

ThismethodcanbeusedtochangetheZoneIDwhilerendering.

stopRefresh()

ThismethodcanbeusedtostoptheAdfromrefreshing.ItisadvisabletocallthismethodinonStop.

resumeRefresh()

WhenstopRefresh()isusedthismethodcanbeusedtoresumerefreshingoftheAd.Itshouldideally
beplacedintheonStart()methodoftheactivity.

IfandwhenabannerrequestfailstorenderwecontinueshowingthepreviousAdandtheonLoadFailure()
callbackiscalled.
UnmanagedBannersusinggetAd()&show()
AsininterstitialsAdsyoucanprefetchbannersadsusingthegetAd()method.Theonlydifferenceisthe
methodusedtoshowtheAd.Todisplaybanneradsyouwouldneedtocalltheshow()methodinplaceof

Version2.2.2

overlayasshown:

manager.getAd(myZoneID,newAdLoadCallback(){
@Override
publicvoidonLoadSuccess(VservAdadObj){
this.adObject=adObj
adObject.show(context,viewGroup)
}
@Override
publicvoidonLoadFailure(){
Log.d(tag,FailedingettingAd)
}
@Override
publicvoidonNoFill(){
Log.d(tag,"NoAdFound")
}
})

TestingIntegration

TheVservSDKIntegrationcanbetestedbyeithersettingyourintegrationtotestmodeforcertaindevicesorby
usingtheTestZonesprovidedbyVserv.
AddingTestDevices
TheVservSDKallowsyoutosetanumberofDevicesasTestDevicesbypassingtheirAdvertisingIDtothe
SDK.YoucanaddtestdevicesusingtheaddTestDevice()methodwhichtakesincommaseparatedidasits
parameters.

manager.addTestDevice(AdvertisingID1,AdvertisingID2,AdvertisingID3)

EachDevicesAdvertiserIDcanbeseeninitsDeveloperOptionsscreen,inadditiontheVservSDKdisplays
thedevicesAdvertiserIDinthelogunderthetagvserv.
UsingtheTestZones
YoucanalsotestyourintegrationacrossoursolutionsbyusingthefollowingZoneIDs

BillboardTestZoneID:8063
BannerTestZoneID:20846

Note:PleasemakesureyourproductionAppdoesnothavetheseZonesasyouwouldnotbeearningrevenue
usingtheseZones.

Version2.2.2

VservManagerOptions

Ifyourecollect,wementionedaboutsettingvariousoptionsontheVservManagertocontrolwhatkindofAds
aredeliveredtoyourapplicationandyouhaveseenafewoftheseearlier.

TheseoptionsareavailableviasettermethodontheVservManagerinstanceandneedtobecalledpriorto
callingthedisplayAd,renderAdorgetAdmethods.

Themethodsarelistedbelow:

MethodName Description
setAge(Stringage) SettheAgeoftheuser.
setBirthDate(StringbirthDate) Setthedateofbirthoftheuser
setCity(Stringcity) SettheCityoftheuser.
setCountry(Stringcountry) Setthecountryoftheuser
setEmail(Stringemail) Settheemailoftheuser
setGender(Gender) Setthegenderoftheuser,either
Gender.FEMALEorGender.MALE
AppendixA:ProGuardSetting
IfyouareusingProguardtoobfuscateyourAndroidcode,youwillneedtoaddthefollowingentriestoyour
Proguardconfigurationincaseyouhaveanyissues:
keepattributes*Annotation*,JavascriptInterface,Exceptions,InnerClasses,Signature

keeppublicclassmobi.vserv.android.ads.*{
public<fields>
public<methods>
}

keeppublicclassmobi.vserv.android.downloader.*{
public<fields>
public<methods>
}

keeppublicclassmobi.vserv.org.ormma.**{
public<fields>

Version2.2.2

public<methods>
}

keeppublicclasscom.google.android.gms.**{
<fields>
<methods>
}

keeppublicenummobi.vserv.android.ads.*{
<fields>
<methods>
}
AppendixB:OptionalPermissions
<usespermissionandroid:name="android.permission.READ_PHONE_STATE"/>
<usespermissionandroid:name="android.permission.SEND_SMS"/>
<usespermissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<usespermissionandroid:name="android.permission.ACCESS_COARSE_LOCATION"/>
<usespermissionandroid:name="android.permission.READ_CALENDAR"/>
<usespermissionandroid:name="android.permission.WRITE_CALENDAR"/>
<usespermissionandroid:name="android.permission.READ_CONTACTS"/>
<usespermissionandroid:name="android.permission.WRITE_CONTACTS"/>
<usespermissionandroid:name="android.permission.CALL_PHONE"/>
<usespermissionandroid:name="android.permission.BLUETOOTH"/>
<usespermissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>

Version2.2.2