Vserv VMAX

Android
Unity Plugin

Contents
Introduction
Prerequisites
Download the Plugin
Setting up your Unity Project
Integrating the Vserv VMAX Unity Plugin
Requesting Vserv Ads
Requesting Interstitials
Managed Method
Unmanaged Method
Requesting Banner Ads
Managed Method
Unmanaged Method
Managing Refresh Rate for Banner Ads
Set Ad Listener:
Set View Mandatory Listener:
Testing Integration:
Adding Test Devices
Using the TestZones
Mediation:
Mediation With Incent Partners:
Appendix A : Permission

Introduction
The Vserv VMAX Unity Plugin is designed to help you integrate Ads in your Unity application for Android.

Prerequisites
Before you begin, we need to make sure of a few things:
You have a Vserv Developer Account. If you have one, go to Step 2. If you do not, sign up at our Developer
Portal.
Note down your ZoneID. This will be required later on when you request Ads. The default ZoneID will be
available in your welcome email or you could visit http://mp.vserv.com/ad-spot-list.html to get a list of all your
zones.

Download the Plugin

The first step to integrating Vserv VMAX Unity Plugin in your Unity application is to download our plugin.
We suggest that you unzip the plugin into a temporary folder. Assuming that the folder is
[ANDROID_VMAX_UNITY_PLUGIN_FOLDER], you will see the following contents:

AndroidVMAXUnityPlugin/

This is the Vserv Plugin, its packaged as an

Unity Android Plugin

AndroidVMAXUnitySampleApp/

Sample Unity project source code that

demonstrates Unity Plugin integration

AndroidVMAXIncentUnityPlugin/

This is the Vserv Plugin, its packaged as an

Unity Android Plugin [Use this for incent ads
only]
Sample Unity Project source code that
demonstrate Unity Plugin integration [Use this
for incent ads only]

AndroidVMAXIncentUnitySampleApp/

Setting up your Unity Project

We need to complete a few steps first to ensure that your Unity project is setup with the Vserv Plugin. This
involves the following:

Integrating the Vserv VMAX Unity Plugin

You need to import the Vserv VMAX Android Unity plugin into your Unity workspace, Right click on your
Assets panel and select Import Package > Custom Package.

Next you need to add the VservPlugin.cs script from the VservUnityPlugin folder into your project. You can just
drag and drop the file into your Assets panel. This script is a helper script which encapsulates all the Vserv
VMAX methods into simple function calls.
Now select your Camera and add a script via the Inspector panel

You now set up the import directive in your script

using VservPlugin;

Add the following into your AndroidManifest.xml file. If you are not using a custom manifest you can create
one and place it the Assets directory and then add the following.

<activity
android:name="com.vserv.android.ads.vast.VastBillBoardActivity
android:configChanges="touchscreen|keyboard|keyboardHidden|navigation|orientation|screenLayout|
uiMode|screenSize"
android:windowSoftInputMode="adjustPan"
android:label="@string/app_name" ></activity>
<activity android:name="com.vserv.android.ads.webview.WebViewFullscreenActivity
android:configChanges=
"touchscreen|keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize"
android:windowSoftInputMode="adjustPan" >
</activity>
You also need to add the following permissions in the Manifest file:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Note : If you are using our AndroidVMAXUnityPlugin, then after importing that you will find that
google_play_services-lib folder is added there in AndroidVMAXUnitySampleApp/Assets/Plugins/Android path.
If you want to use your own google-play-services_lib folder, then you have to manually replace that folder with
your own google-play-services_lib folder.
If you execute ourAndroidVMAXUnitySampleApp then google_play_services-lib folder is already added.
Your project is now ready to display Ads from the Vserv VMAX SDK.

Requesting Vserv Ads

The Vserv Unity Plugin provides various mechanisms to request for Ads in your Unity game application. The
plugin provides both simple fully-managed Ad request methods and also the get & show Ad methods to enable
pre fetching of ads.

Requesting Interstitials
Before you request for an Interstitial Ad, make sure you construct an object of the Class VservPlugin and pass
the zoneId and uxType as the parameter into constructor. Once initialization is done, requesting for an Interstitial
Ad can be done in two ways - Managed and Unmanaged.

Managed Method

For a managed way request, just call the loadAd() API. The example below is set up to show an
Interstitial Ad.
void Start () {
vservPluginInterstitial = new VservPlugin ("8063",1); // the 2nd parameter is 1 passed for
// creating object of VservPlugin for Interstitial
}
void Update () {
if (Input.GetKeyUp(KeyCode.Escape)) {
Application.Quit();
}}
void OnGUI() {
// code to create GUI
vservPluginInterstitial.loadAd() // it returns the callback of adViewDidLoadAd()
}
Some other methods the API expose:
vservPluginInterstitial .setAdListener(mAdListener); // To get Ad callbacks
vservPluginInterstitial .setTestDevices(avdId); // To enable test mode
vservPluginInterstitial .setTimeOut(20); //To set timeout if Ad failed to fetch

To set Demographic parameters:

Why Demographic?
Location and demographic targeting information may also be specified. Out of respect for user privacy, Vserv
asks that you only specify location and demographic data if that information is already used by your app. Below
are example of optional functions :

vservPluginInterstitial .setDOB(dob); // To set date of birth of user

vservPluginInterstitial .setAge(age); // To set Age of user
vservPluginInterstitial .setEmail(email); //To set Email id of user
vservPluginInterstitial .setCountry(country); // To set Country of user
vservPluginInterstitial .setCity(city); // To set city of user
vservPluginInterstitial .setGender(gender);
//To set gender of user
Unmanaged Method
For an unmanaged way request, you firstly should call the cacheAd() API. Later, you can show the
cached ad whenever you wish to using the showAd() API. The example below is set up to show an
Interstitial Ad using cacheAd() and showAd() APIs combination.
void Start () {
vservPluginInterstitial = new VservPlugin ("8063",1);
// It is a test zone, please replace this with your zone id

}
void Update () {
if (Input.GetKeyUp(KeyCode.Escape)) {
Application.Quit();
}}
void OnGUI() {
// code to create GUI
//Call cache ad API to cache
vservPluginInterstitial.cacheAd()
// This will cache Ad and sends it respective callback through Ad Listener. If
//cached successfully it will come in adViewDidCacheAd(VservAdView adView)
//You can call the showAd() API whenever you need to
// show the cached ad
vservPluginInterstitial.showAd() }
8

Requesting Banner Ads

Before you request for a Banner Ad, construct an object of the Class VservPlugin and pass the zoneId
and uxType as the parameter into constructor. Once initialization is done, You need to set the position
of the banner before you show it. Use setPosition() API to set the position of the Banner.Now once
this initialization part is done, you can request for a Banner Ad in two ways - Managed and Unmanaged.

Managed Method

For managed Banner Ad, you just need to call the loadAd() API.The example below is set up to show a
Banner Ad.
void Start () {
vservPluginBanner = new VservPlugin ("20846",0); // the 2nd parameter is 0 passed for
//creating object of VservPlugin for Banner
}
void Update () {
if (Input.GetKeyUp(KeyCode.Escape)) {
Application.Quit();
}}
void OnGUI() {
// code to create GUI
vservPluginBanner .setPosition(8) // for Bottom Center
vservPluginBanner .loadAd()
}
Unmanaged Method
For an unmanaged way request, you firstly should call the cacheAd() API. Later you can show the cached ad
whenever you want by using showAd() API.Dont forget to set the position of the Banner Ad by calling
setPosition() API before calling the showAd() method.
The example below is set up to show a Banner Ad using cacheAd() and showAd() API combination.

void Start () {
vservPluginBanner = new VservPlugin ("20846",0);
}
9

void Update () {
if (Input.GetKeyUp(KeyCode.Escape))
{
Application.Quit();
}}
void OnGUI() {
// code to create GUI
//Call cache ad API to cache
vservPluginBanner .cacheAd()
//You can call the showAd() API whenever you need to show
//the cached ad
vservPluginBanner .setPosition(8);
vservPluginBanner .showAd()
}
The possible positions are :
1 - Top_Left
2 - Top_Center
3 - Top_Right
4 - Center_Left
5 - Center
6 - Center_Right
7 - Bottom_Left
8 - Bottom_Center
9 - Bottom_Right

10

Managing Refresh Rate for Banner Ads

The default refresh rate for Banner ads is 30 seconds. You can, however, manage the the frequency at which
the Banner Ads are refreshed using the setRefreshRate() method. If you set a value less than 30 seconds, the
default value is taken as the refresh rate.
Here is the example to setRefreshRate():
vservPluginBanner .setRefreshRate(45); // parameter is 45 second passed to it.

Additionally, you can also have a call to the APIs pauseRefresh(), stopRefresh() and
resumeRefresh() to carry out functions like pausing, stopping and resuming refresh.
To set Demographic parameters using VMAX API use below mentioned APIs.
setAge(int age) // set the age
setDOB(DateTime dob) // set DOB
setRefresh(bool refresh) // set Refresh
setTimeOut(int timeOutSeconds) // set the timeout
setRefreshRate(int refreshRate) // set Refresh Rate
setCity(string city) // set the user City
setGender(string gender) // set the user Gender
setEmail(String emailId) // set the user email
setCountry(String) // set the user country
setLoginId(string loginId) // to set user Login Id
setSection(string section) // set the user section

11

Set Ad Listener:
Here Callbacks are received based on success,failure and interactions with Ad
This will give callbacks respectively on successful and unsuccessful fetching of Ads
void OnGUI()
{
vservPluginInterstitial.setAdListener(); //register for the listener to get callback
}
/* This Call back method is invoked when Ad is clicked or interaction happen with Ad */
public void didInteractWithAd(string unusedMessae)
{
// your code here
}
/* This Call back method is invoked when fetched Ad is successfully rendered */
public void adViewDidLoadAd(string unusedMessae)
{
// your code here
}
/* This Call back method is invoked when Ad is going to be shown */
public void willPresentOverlay(string unusedMessae)
{
// your code here
}
/* This Call back method is invoked when Ad is dismissed */
public void willDismissOverlay(string unusedMessae)
{
// your code here
}
/* This Call back method is invoked when Ad is cached successfully */
public void adViewDidCacheAd(string unusedMessae)
{
// your code here
}
/* This Call back method is invoked when Ad is failed to load because of any reason if any. */
public void didFailedToLoadAd(string unusedMessae)
{
// your code here
}

12

/* This Call back method is invoked When Ad is going to leave current App and open any outside app */
public void willLeaveApp(string unusedMessae)
{
// your code here
}

13

Set View Mandatory Listener:

To get the callback of this listener you must have to call the setDisplayOffline(bool value) API . You will get
below mentioned callback by setting the setViewMandatoryListener().
void OnGUI()
{
vservPluginInterstitial.setAdListener(); //register for the listener to get callback
}
/* This Call back method is invoked when Ad is clicked or interaction happen with Ad */
public void onConnectionFailure(string unusedMessage)
{
// your code here
}

14

Testing Integration:
The Vserv SDK Integration can be tested by either setting your integration to test mode for certain devices or by using the
Test Zones provided by Vserv.

Adding Test Devices

The Vserv SDK allows you to set a number of Devices as Test Devices by passing their AdvertisingID to the
SDK. You can add test devices using the setTestDevices() method which takes in comma separated id as its
parameters.
For example :
setTestDevices(string testDeviceAvdIds) // comma separated avdIds for adding devices for testing
Each Devices AdvertiserID can be seen in its Developer Options screen, in addition the VMAX Unity displays the
devices AdvertiserID in the log under the tag Unity.

Using the TestZones

You can also test your integration across our solutions by using the following ZoneIDs
Billboard Test ZoneID: 8063
Banner Test ZoneID: 20846
Note: Please make sure your production App does not have these Zones as you would not be earning revenue
using these Zones.

15

Mediation:
To Support Mediation with partners:
It consists of all supported Client to Server integration Partners like Admob, Facebook, Tapjoy, Vungle, Adcolony,
Charboost, Flurry,Millennial Media,Bee 7.

Following are the partners and its respective libraries:

1.) To exclude Adcolony from mediation, delete "adcolony.jar" from "Assets/Plugins/Android" folder. And
delete code <Start Adcolony>..... <End Adcolony> from AndroidManifest.xml file in
"Assets/Plugins/Android" folder.
2.)To exclude FaceBook from mediation, delete "AudienceNetwork.jar" from "Assets/Plugins/Android"
folder. And delete code <Start Facebook>..... <End Facebook> from AndroidManifest.xml file in
"Assets/Plugins/Android" folder.
3.) If you don't want Chartboost in app, delete "chartboost.jar" from Vserv library project in
"Assets/Plugins/Android" folder. And delete code <Start Chartboost>..... <End Chartboost> from
AndroidManifest.xml file in "Assets/Plugins/Android" folder.
4.) To exclude Admob from mediation, unlink "Google Play service Library Project" from Vserv library project in
"Assets/Plugins/Android" folder. And delete code <Start Admob>..... <End Admob> from
AndroidManifest.xml file in "Assets/Plugins/Android" folder.
5.) To exclude Tapjoy from mediation, delete "tapjoyconnectlibrary.jar" from "Assets/Plugins/Android"
folder.And delete code <Start Tapjoy>.....<End Tapjoy> from AndroidManifest.xml file in
"Assets/Plugins/Android" folder.
6.) To exclude Vungle from mediation, delete following libraries
"vungle-publisher-adaptive-id-3.2.2.jar","nineoldandroids-2.4.0.jar","javax.inject-1.jar","dagger1.2.2.jar" from "Assets/Plugins/Android" folder.in "libs" folder. And delete code <Start Vungle>.....
<End Vungle> from AndroidManifest.xml file in "Assets/Plugins/Android" folder.
7.) To exclude MillennialMedia from mediation, delete following libraries "MMSDK.jar" from
"Assets/Plugins/Android" folder. And delete code <Start Millennial Media>..... <End Millennial
Media> from Android Manifest file in "Assets/Plugins/Android" folder.
8.) To exclude Flurry from mediation, delete following libraries
"FlurryAnalytics-4.2.0.jar","FlurryAds-4.2.0.jar" from Vserv library project.
16

in "libs" folder. And delete code <Start Flurry>..... <End Flurry> from Android Manifest file in Vserv Library
project.
Note 1: To support video Ads with mediation partners like Vungle, Adcolony, Chartboost make sure to add
below attribute in <Application> tag. Already added in attached sample app.
<application android:hardwareAccelerated="true">
Note 2: All mandatory permissions required by partners are already added in Unity Plugin. No need to add them
again in your application manifest
Note 3: For Vungle partner it is recommended to use the old google_play_services-lib which is having
LocationClient class in it. In the new version of google_play_services-lib, the LocationClient class is removed. As
a result your application will get crashed while using new google-play-services_lib for this partner.
Suggestion : Use latest version of Google Play service Library to support all its native functions.
Sample app with zip have all these above settings configured already.

17

Mediation With Incent Partners:

Incentivize mobile ad networks allow app developers and mobile advertisers to reward users for an action. The
user is required to complete a specific task in exchange for a prize, such as virtual currency. So increase your
app revenue by serving offers and monetizing your non-paying users.

Complete the following steps to support mediation with incent Partners like Tapjoy and Bee7.
1. Add the Bee7 Gamewall libraray (bee7androidgamewall) and bee7androidgamewallunity folder
provided in our package to PROJECT_PATH\Assets\Plugins\Android folder.
2. Add google play services lib folder to PROJECT_PATH\Assets\Plugins\Android folder. The google play
services is required for both Tapjoy and Bee7 partners.
3. Fill the required details on the Vserv web interface at mp.vserv.com/ad-spot-list.html to start mediation for
that zone
Initialize Incent ads as shown below :
VservPlugin vservPlugin;
vservPlugin = new VservPlugin (YOUR_BILLBOARD_ZONE,YOUR_AD_TYPE);
vservPlugin.setIncentAd(true); // this is important for initialising incent ads.
vservPlugin.setCallbackHandlerName(gameObject.name);

Set the listener for Incent ads :

vservPlugin.initializeVservCustomIncentListener();

18

Callbacks for incent ads :

public void onUpdateVirtualCurrency(string virtualCurrency)

{
//Debug.Log("onUpdateVirtualCurrency Called : "+virtualCurrency);
}
public void onUpdateFailedVirtualCurrency(string errormsg)
{
//Debug.Log("onUpdateFailedVirtualCurrency Called : " + errormsg);
}

You can call below mentioned api exposed for incent ads.
To get the total virtual currency :
vservPlugin.getTotalVirtualCurrency();

To spend Virtual Currency :

vservPlugin.setSpendVirtualCurrency(int currency);

To award virtual currency :

vservPlugin.awardVirtualCurrency(int currency);

Important :
For Bee7 Incent partner, after adding bee7androidgamewallunity folder as mentioned above.Open the
bee7androidgamewallunity folder and search for AndroidManifest.xml
Change the android:scheme="vservdemopublisher" to your scheme as provided by Bee7 dashboard.
( you will get it after registering on Bee7)

19

Appendix A : Permission
<!-- Mandatory -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!--Otional Permission:-->
<!-- Vserv ads Store picture option -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!-- Vserv ads to read network state -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Vserv ads to read network state -->

<!-- <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> -->
<!-- Vserv ads to location based ads -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- Vserv ads to phone info -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- Vserv ads to location info -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Mandatory for Tapjoy/Charboost/Vungle/Adcolony/MillenialMedia -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- For Bee7 required permission -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

20