AdClient SDK for Android User Manual 

    This manual provides a simple step by step guidance for a quick and painless                           

integration of AdClient advertising into your applications.  

1. Preparation  

Place the AdClient SDK JAR file (adclientsdkforandroid*.jar) in your build path                     similar to any other external jar that you might already have included into your project. This                               is most likely to be found under the "libs" subdirectory of your project's root directory. 

For Eclipse IDE projects steps are the following: • Go to the Properties tab of your project. • Select "Java Build Path" from the panel on the left side. • Select "Libraries" tab in the main window. • Click "Add External JARs " button. • Select the JAR (adclientsdkforandroid*.jar). • To add the SDK to your Android project, Click "OK". • Go to “Order and Export” tab from the main window • Check the adclientsdkforandroid*.jar. 

AdClient SDK has following dependencies: • Android Support v4 library 

Add advertising network specific sdk jars as well to ensure ability to retrieve ads from                             the networks that you are planning to use as ad sources.  

 

  2. Setting permissions in Manifest.xml file 

 Given table represents vendor specific info for adding into Your AndroidManifest.xml                     

configuration along with minimal required API level and highest version of vendor sdk which                           AdClient SDK has been tested against:  

Vendor  Minimal API Level 

Permissions  Tested Version 

Required Activities 

AdMob  9  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE 

Google Play   Services 5.0.77 

  

InMobi  8  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE  optional: 1.ACCESS_COARSE_LOCATION 2.ACCESS_FINE_LOCATION 3.ACCESS_WIFI_STATE 

4.5.0 

4.CHANGE_WIFI_STATE 5.READ_LOGS 6.VIBRATE 7.RECORD_AUDIO 8.WRITE_EXTERNAL_STORAGE 9.READ_CALENDAR 10.WRITE_CALENDAR 11.com.google.android.gms.permission.ACTIVITY_RECOGNITION 

e/Theme.Translucent.NoTitleBar" />     

Smaato  5  mandatory: 1.INTERNET  optional: 1.READ_PHONE_STATE 2.ACCESS_NETWORK_STATE 3.ACCESS_COARSE_LOCATION 4.ACCESS_FINE_LOCATION 5.WRITE_EXTERNAL_STORAGE 6.READ_CALENDAR 7.WRITE_CALENDAR 8.GET_ACCOUNTS 

4.3.2    If you are using Google Play           Services SDK:  

InnerActive  8  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE  optional: 1.READ_PHONE_STATE 2.ACCESS_COARSE_LOCATION 3.ACCESS_FINE_LOCATION 4.WRITE_EXTERNAL_STORAGE 

5.0.2     

MillenialMedia 

3  mandatory: 1.INTERNET 2.WRITE_EXTERNAL_STORAGE 3.READ_PHONE_STATE 4.ACCESS_NETWORK_STATE 

4.5.1   

android:name=”com.millennialmedia.android.VideoPlayer” android:configChanges="keyboardHidden|orientation|keyboard" /> 

Yoc Performance 

5  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE  optional: 1.ACCESS_FINE_LOCATION 2.READ_PHONE_STATE 3.WRITE_CALENDAR 4.CALL_PHONE"> 5.SEND_SMS 6.WRITE_EXTERNAL_STORAGE 

3.0.2   

TapIt  4  mandatory: 1.INTERNET 2.READ_PHONE_STATE 3.ACCESS_NETWORK_STATE  optional: 1.ACCESS_FINE_LOCATION 2.ACCESS_COARSE_LOCATION 3.WRITE_EXTERNAL_STORAGE 

1.0       

Wap Start  7  mandatory: 1.INTERNET  optional: 1.ACCESS_FINE_LOCATION 

1.3   

Mojiva  5  required: 1.INTERNET 2.ACCESS_NETWORK_STATE 3.READ_PHONE_STATE  optional: 1.ACCESS_FINE_LOCATION 2.READ_CALENDAR 3.WRITE_CALENDAR 4.CALL_PHONE 5.SEND_SMS  6.CAMERA 7.WRITE_EXTERNAL_STORAGE 8.WAKE_LOCK 

3.0.2   

AdIQuity  9  mandatory: 1.INTERNET  optional: 1.ACCESS_NETWORK_STATE 2.READ_PHONE_STATE 

2.6   

3.ACCESS_COARSE_LOCATION 4.ACCESS_FINE_LOCATION 

Cauly  4  mandatory: 1.CALL_PHONE 2.INTERNET 3.ACCESS_FINE_LOCATION 4.ACCESS_NETWORK_STATE 5.WRITE_EXTERNAL_STORAGE 6.READ_EXTERNAL_STORAGE 

1.4.8   

Vserve  8  mandatory: 1.INTERNET 2.ACCESS_COARSE_LOCATION 3.ACCESS_COARSE_LOCATION 4.ACCESS_NETWORK_STATE 

1.2   

AdClient  4  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE   optional: 1.WRITE_EXTERNAL_STORAGE 2.READ_PHONE_STATE 3.ACCESS_FINE_LOCATION 4.ACCESS_COARSE_LOCATION 

    

MassiveImpact 

7  1.INTERNET 2.ACCESS_NETWORK_STATE  

3.6   

MobFox  8  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE  optional: 1.READ_PHONE_STATE 2.ACCESS_FINE_LOCATION 

4.1.6    

n|screenLayout|uiMode|screenSize|smallestScreenSize"/>  activity holding banner should       have android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" declared.  

Airpush  9  mandatory: 1.INTERNET 2.ACCESS_NETWORK_STATE 3.READ_PHONE_STATE 4.WRITE_EXTERNAL_STORAGE  optional: 1.ACCESS_COARSE_LOCATION 2.ACCESS_FINE_LOCATION 3.ACCESS_WIFI_STATE 

Standard SDK 1.0 Beta 

   

Vdopia  8  1.INTERNET 2.ACCESS_NETWORK_STATE 3.GET_ACCOUNTS 4.READ_PHONE_STATE 5.ACCESS_WIFI_STATE  

LightWeight SDK for Android 

  

Vungle  9  1.INTERNET 2.WRITE_EXTERNAL_STORAGE 3.ACCESS_NETWORK_STATE 

3.2.2   

/>  

Amazon  4  1.INTERNET 2.ACCESS_COARSE_LOCATION 3.ACCESS_FINE_LOCATION 4.ACCESS_NETWORK_STATE 5.ACCESS_WIFI_STATE  

Amazon Mobile Ads   API 5.4.227 

 

VideMob  10  mandatory:  added automatically  optional: 1.ACCESS_NETWORK_STATE 2.ACCESS_WIFI_STATE 3.ACCESS_COARSE_LOCATION 4.ACCESS_FINE_LOCATION 

2.8.8    

BrightRoll  8  1.INTERNET 2.ACCESS_FINE_LOCATION 3.ACCESS_NETWORK_STATE 

20140717    

AerServ  10  mandatory:  1.INTERNET 2.ACCESS_COARSE_LOCATION 3.ACCESS_FINE_LOCATION 4.ACCESS_NETWORK_STATE 5.READ_PHONE_STATE 6.com.google.android.providers.gsf.permission.READ_GSERVICES  optional: 1.WRITE_EXTERNAL_STORAGE 2.VIBRATE 

2.25rc1    

android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"/>  

MoPub  9  mandatory:  1.INTERNET 2.ACCESS_NETWORK_STATE  optional: 1.ACCESS_COARSE_LOCATION 2.ACCESS_FINE_LOCATION 3.WRITE_EXTERNAL_STORAGE  

3.5.0       

 Here are some examples: 

 *   

INTERNET  Allows application to use network connection           sockets. Make sure the INTERNET permission is             enabled to allow the SDK to access the network                 and exchange ads with ad servers. 

READ_PHONE_STATE*  Allows application to access the phone state in               read only mode.This permission is enabled for             

getting the device ID, which allows app to               benefit from highly targeted campaigns. 

 * In case of using AdMob, InMobi, YOC Performance or Mojiva as ad providers this permission is not required.  

You can enable location targeting in your app, which means configuring your app to                           receive locationbased ads. Enable the optional ACCESS_COARSE_LOCATION and               ACCESS_FINE_LOCATION permissions to allow the SDK to access the user location details.   

ACCESS_COARSE_LOCATION  Allows an application to access coarse (CellID,             WiFi) location. 

ACCESS_FINE_LOCATION  Allows an application to access fine (GPS)             location. 

 ACCESS_NETWORK_STATE permission allows to detect network connectivity and in                 

this way enable ad rotation in your app.  

ACCESS_NETWORK_STATE  Allows an application to view the state of all                 networks. 

WRITE_EXTERNAL_STORAGE  Allows an application to write to external storage. 

READ_EXTERNAL_STORAGE  Allows an application to read to external storage. 

CALL_PHONE  Allows application to perform phone calls. 

 With all the above your final AndroidManifest.xml may look something like this: 

       

Also, you need to specify synchronization service, download receiver and popup                     activity in your application’s manifest file, somewhere between and                    tags:                           

 The below lines need to be added, too, because they are required by AdMob and                             

InMobi mobile advertising networks:  

 

  

In case of using Millenial Media ads following needs to be added:   

   

 When using Inneractive as ad source add following to Your AndroidManifest.xml file: 

  

 When using TapIt as ad provider add following into AndroidManifest.xml before                     

:  

 

 In case of using Cauly as ad provider clicks may not be accounted by system.  

 Given all the above, your sample application’s Manifest.xml file is likely to look like this: 

   

                   

 

                                                             |uiMode|screenSize|smallestScreenSize"/>      

  

      

  

3. Obtaining your key  In order to ensure the best experience you should disable refresh in any external                           

ad providers that you may use.   Make sure you have your key on hand for the rest of the implementation, taken from                               

our website or provided by your personal account manager. Key is essential entity that                           identifies you within the system. It is the only mandate prerequisite for getting started as                             AdClientSDK user. 

   

4. Integration  

To make the integration process more flexible and as easy as possible, we are offering                             two ways of adding the AdClientView to your application: 

1.  As a tag in  the layout XML file. 2. As API for forming and displaying ad viewing element from your code at  runtime.  Way #1:  Declarative description in layout file. In order to add AdClientView to your layout : 

 a. Add attributes set in the XML layout for this view into res/values (attrs.xml).      Paste the following configuration parameters into your attrs.xml file:        

                                                          

  

                   

Here are the mandatory parameters you MUST add to your layout file:  

key  thekey provided during the registration process 

adServerUrl  Target URL for ads requests. 

 Here are the optional parameters you can add to your requests: 

 

refreshInterval  Time frequency of ads refreshing, in seconds. The minimum refresh interval                     is 15 seconds, and the maximum is 90 seconds, which is 1.5 minutes. In                           case this parameter is omitted or entered value is out of specified bounds,                         value of 15 seconds is being applied.  IN ORDER TO ENSURE BEST USER EXPERIENCE WE COMPEL YOU                   TO DISABLE ALL EXTERNAL REFRESH  MECHANISMS. Not being used while requesting interstitial ad. 

adType*  The type of the ad you want to display. Currently supported values are:           BANNER_320X50           BANNER_300X250           BANNER_468X60               BANNER_728X90           BANNER_120X600           INTERSTITIAL 

 viewBackground 

Background color of ad displaying view given as word describing                   specified color.  

app:viewBackground = “magenta”  Defaults to black when not specified explicitly.  

custom  Additional parameters string. 

 * In case if some outer ad network doesn’t support some format, it rollbacks to default banner_320X50.  

b. Insert a reference into the attrs.xml file in your layout element :  Insert a reference to the attrs.xml file in your layout element by adding xmlns line that                               

includes your package name specified in AndroidManifest.xml. For example, if your package                       

name is com.adclient.sample, you would include this line:  xmlns:app = "http://schemas.android.com/apk/res/com.adclient.sample" . 

 c. Add  AdClientView to the layout: 

  

 Your sample application may look something like this: 

    

 

 

  

  

Way #2:  Imperative creating at runtime. In order to create AdClientView element programmatically:  a. Prepare configuration parameters map: 

http://my.ads.host:8080/http://schemas.android.com/apk/res/androidhttp://schemas.android.com/apk/res/com.adclient.sample

 Map params = new HashMap(); params.put(ParamsType.KEY,”49d835910115c8523f80db8405b77”);  params.put(ParamsType.REFRESH_INTERVAL,”25”); Map customParams = new HashMap(); customParams.put("make", "1234"); configuration.put(ParamsType.CUSTOM, customParams);    

                Here are all the parameters that you can use:  

ParamsType.KEY  User key. ParamsType.REFRESH_INTERVAL  time for ad refresh. ParamsType.ADTYPE  specific ad type. ParamsType.CUSTOM  map of additional parameters(key,value pairs). ParamsType.AD_SERVER_URL  target URL for ad requests. 

b. Create AdClientView object using one of the following constructors:  

public AdClientView(Context context); public AdClientView(Context context, AttributeSet attrs); public AdClientView(Context context, AttributeSet attrs, int defStyle); 

 c. Assign created parameters map to AdClientView object: 

 adClientView.setConfiguration(params); 

 d. Place created adClientView somewhere within your existing layout: 

 LinearLayout myLayout = (LinearLayout) findViewById(R.id.main); myLayout.addView(adClientView); 

 AdClientView element starts requesting for ads right after creation. In order to properly                         

manage AdClientView lifecycle call it methods resume(), pause(), and destroy() in the                       corresponding Activity methods:  

    @Override     protected void onResume() {         super.onResume();         if (adClientView != null) {             adClientView.resume();         }     }      @Override     protected void onPause() {         if (adClientView != null) {             adClientView.pause();         }         super.onPause();     }  

    @Override     protected void onDestroy() {         if (adClientView != null) {             adClientView.destroy();         }         super.onDestroy();     }  

 5. Interstitial ads 

 In case of declaring AdClientInterstitial view as part of the layout markup interstitial                         

going to   be shown once when layout being inflated:   

 AdClientInterstitial class can also be used programmatically to trigger interstitials                   

showing in any place of you app:  

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); final Context context = this; final View layout = findViewById(R.id.mainLayout);  final AdClientInterstitial interstitial = new AdClientInterstitial(context); HashMap configuration = new HashMap(); configuration.put(ParamsType.KEY, "8ded375f9ac9fe65e8ccd84a99b5439c"); configuration.put(ParamsType.ADTYPE, AdType.INTERSTITIAL.toString()); interstitial.setConfiguration(configuration);  interstitial.setServerAdListener(new ServerAdListener() { 

public void onReceivedAd(AbstractAdClientView adClientView) { Log.d("TestApp", "> Ad received callback."); 

} public void onFailedToReceiveAd(AbstractAdClientView adClientView) { 

Log.d("TestApp", "> Ad failed to be received callback."); }  public void onShowAdScreen(AbstractAdClientView adClientView) { 

Log.d("TestApp", "> Ad show ad screen callback."); } 

});  ((ViewGroup)layout).addView(interstitial); 

 Button button = (Button) findViewById(R.id.button); button.setOnClickListener(new View.OnClickListener() { 

@Override public void onClick(View view) { interstitial.show(); } 

}); }  In order to properly manage AdClientInterstitial lifecycle call it methods resume(),                     

pause(), and destroy() in the corresponding Activity methods:  

    @Override     protected void onResume() {         super.onResume();         if (interstitial != null) {             interstitial.resume();         }     }      @Override     protected void onPause() {         if (interstitial != null) {             interstitial.pause();         }         super.onPause();     }      @Override     protected void onDestroy() {         if (interstitial != null) {             interstitial.destroy();         }         super.onDestroy();     }   6. Debugging MRAID ads  AdClient Android SDK gives You an option to debug custom MRAIDpowered ads. You                         

can use mraid.logEntry(message) at any place in Your richmedia banner to pass some                         piece of information to Android logging facility.  

7. Location Updates  

AdClient SDK for Android allows the API to control location updates retrieval from                         users’ devices. 

Use the LocationWatcher interface to access location update management methods: boolean watch() ensures that coordinates of the user’s device are sent with every ad                             

request; boolean unWatch() removes location listener, no coordinates will be requested or sent with                           the ad request;    

final AdClientView banner = (AdClientView) findViewById(R.id.bannerView); banner.getLocationWatcher().unWatch();  

These methods are called automatically when the visibility of the application window                       changes, so you cannot use them to permanently stop location updates. Instead, to                         permanently change location update methods and intervals use: 

 Map locationProviderMap = banner.getLocationWatcher().getLocationProviderMap(); 

 For instance, to set location update interval (which is one hour by default) to 5                             

seconds for the network provider and to 10 minutes for the GPS provider call:  

locationProviderMap.get(LocationManager.NETWORK_PROVIDER).setMinTime(5000); locationProviderMap.get(LocationManager.GPS_PROVIDER).setMinTime(600000); 

 and to completely disable location updates call locationProviderMap.clear() for each                   

banner.  

8. Test Mode  

Some (but not all) vendor SDKs allow specifying test mode for serving ads. To make                             Adclient SDK enable the test mode for some of the supported SDKs call 

 AdClientView.setTestMode(true);  Please note that test mode may be applied only partially so some ads will continue to                               

be served in production mode.