Integration – App – Android SDK

Last Updated

October 12, 2020

  • Added FLAG_ACTIVITY_NEW_TASK flag to run activity from outside context.

June 12, 2018

  • Handle RuntimeException within sdk media player.

April 19, 2018

  • Fix publisher reported crash issue for accessing methods on ViewTreeObserver which is no longer alive.

April 2018

  • Fix SDK MediaPlayer runtime exception when accessing track information on illegal state.

March 2018

  • Support Mraid 3.0 new features for the improvement of user’s ad experience.
  • Fix publisher reported NPE issues.

January 2018

  • Fix multiple publisher reported NPE crash issues.

October 2017

  • Native header bidding support.
  • Now it is possible to check the CPM value of ad before running it.
  • Fix several publisher reported crash issues.

September 2017

  • WSApplication class is introduced to speed up AdSpace instance creation.
  • Audio focus for sdk media player is handled considering other application’s audio session.

May 2017

  • Removed unnecessary application tag from AndroidManifest.xml.
  • Fix for ad loading issue with handling special character in the provisioning url.

April 2017

  • Fix null pointer crash in Chrome CustomTab for CustomTabsCallback.

March 2017

  • Fix scrolling issue with AdSpace integrated inside any scrollable ViewGroup.

February 2017

  • Fix for ad flickering while loading.
  • Fix for html5 video player incompatibility issue.
  • Fix for geolocation permission callback not triggering for requests to access geo-location through WebView.
  • Fix for swipe ad when adSpace is used inside ViewGroup that also react to swipe action.
  • Fix for getting location data.
  • Fix for User Linking crash issue.

January 2017

  • Added support for Chrome Custom Tab shipped with support library 25.x.x.
  • Fix for ad scaling while AdSpace size is set to specific value other than MATCH_PARENT or WRAP_CONTENT


Add the Widespace SDK

Android SDK version 4.10.4 download



Documentation folder

Contains the updated Javadoc of the SDK where you’ll be able to find more specific information about the methods and events available.

Libs folder

Contains the third-party libraries that are used in the SDK. these libraries must be imported in publisher’s apps if they choose to use the JAR and not the AAR. Details on how to do that will follow.

Res folder

Contains the resource files, namely attr.xml, that are used by the SDK. This file must be imported in publisher’s apps resource folder if they choose to use the JAR and not the AAR. Details on how to do that will follow.

JAR file

A standard java library file that may be used in Android projects.


AAR file

The new Android Archive file format that is a new Google standard of libraries that are specifically made for the Android operating system. an AAR file is essentially a zip containing all the aforementioned files (except for the documentation).


ChangeLog file

Contains the log of all notable changes made in the sdk per release.


ReadMe file

Contains integration instruction for the application developer to use this sdk for showing ad.


Android Studio Integration

Android Studio uses a modern build system (Gradle) to build Android projects. Gradle’s Android plugin could be tricky to master but it certainly gives a whole area of opportunities that are hard to achieve with the older Ant build system.

Along with the introduction of Android Studio, a new library format called AAR (Android Archive) was introduced to encapsulate all required files and information that may be used by a library. This way, the developer using the library does not have to care about using AAR as a local resource.


Importing the aar file

For the sake of example let’s assume filename is widespace-sdk-4.10.0.aar. Start with importing the Widespace SDK aar file into your libs folder.

In your build.gradle file

Make sure that your project is following the below min version dependencies:

android {
  compileSdkVersion 27

  defaultConfig {
    minSdkVersion 17 /*or later*/
    targetSdkVersion 27 /*if you're not targeting Oreo use 21 or any version lower than 27*/

Add the following where you define dependencies:

repositories {
  flatDir {
         dirs 'libs'
dependencies {
   /*SDK dependencies*/
  implementation 'com.widespace:*replace_with_name_of_widespace_aar_file*@aar'
  implementation '' /*Minimum required version is 27.*/
  implementation '' /*Minimum required version is 27.*/
  implementation '' /*Minimum required version is 27.*/
  implementation '' /*Minimum required version is 27.*/
  implementation ''
  implementation '' 
  implementation 'org.slf4j:slf4j-android:1.7.10'


Adding permissions

Add Permissions

In your AndroidManifest.xml add the following permissions:

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

Also make sure that you add the below method to any Activity that contains the Widespace Adspace. This in order to notify Marshmallow users with a permission request once it’s about to be used by the SDK instead of when downloading the application. The permissions that the SDK needs to access at the very moment will be requested with “approval” and “denial” options:

public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) 
        AdSpace.onRequestPermissionsResult(requestCode, permissions, grantResults);

Permission Request Code

In order to avoid conflicts between request codes from Widespace SDK and request codes from the App, each request code need to differ. Below you’ll able to see the codes used by Widespace SDK permissions:

Permission Request Code


Start writing code

XML Integration

For this example we call the namespace “widespace” and to implement the ad in our activity_main.xml layout file it usually looks something like this:

<RelativeLayout xmlns:android=""


FuFurther down in our activity_main.xml layout file, one common way to implement an ad display can look like this:


Java Integration

Start by declaring a private AdSpace instance and give it a name. Once that’s done you can continue with initiating the AdSpace inside your onCreate. Below you’ll find an example of how it can look like:


private AdSpace myAdSpace; 

 protected void onCreate(Bundle savedInstanceState)

      //Initializing the AdSpace
      myAdSpace = new AdSpace(this, "bc090549-d9bb-4a34-be19-69d21c6038d5", true, false); //sid, autoStart, autoUpdate
      //Adding the Layout params and attaching the AdSpace to the view
      myAdSpace.setLayoutParams(new LayoutParams(LayoutParams.MATCH_PARENT,
      View view = getWindow().getDecorView().findViewById(; 
      ((ViewGroup) view).addView(myAdSpace);


Native Header Bidding

Native Header Bidding Example Implementation

The following code snippet shows usage of native header bidding in an activity with the currency EUR.

RelativeLayout container = (RelativeLayout) findViewById(;
adSpace = new AdSpace(this, SID, false, false);
adSpace.requestBids("EUR", new BidRequestListener()
    public void onBidReceived(WSBid bid, WSBidException exception)
        if(bid != null)
            if(bid.getCPM() >= CPM_VALUE_OF_INTEREST) // The condition that will select this bid over others
                bid.acceptAndRunAd(); // Calling this method will run the ad associated with this bid object
            Log.d(TAG, exception.getLocalizedMessage());

container.addView(adSpace, new RelativeLayout.LayoutParams(RelativeLayout.LayoutParams.MATCH_PARENT, RelativeLayout.LayoutParams.WRAP_CONTENT));


Life Cycle & Cleanup Process

The AdSpace has three life cycle methods pause(), resume(), destroy() to imitate the lifecycle of Activity/Fragment in which AdSpace is going to be used. In this section you will find code example of how to use the life cycle methods.


In your onPause() & onResume():

    protected void onPause() {

        myAdspace.pause(); /*method pause the update schedular & media player to avoid consuming CPU*/


    protected void onResume() {

        myAdspace.resume(); /*method resume previously paused update schedular & media player*/


Whenever the AdSpace is no longer needed you should call a public method called destroy() to clean up the Adspace. Note that you’ll find three different examples below that demonstrates how to clean up your AdSpace within an Activity, Fragement or RecyclerView:



    public void onDestroy()
      if (myAdspace != null)


    public void onDestroyView()
      if (myAdspace != null)



       Extend our custom RecyclerView adapter
     public class RecyclerViewAdapter extends WSRecyclerViewAdapter

       Make sure you call super onBindViewHolder and onDetachedFromRecyclerView methods in your corresponding overridden methods
     public void onBindViewHolder(RecyclerView.ViewHolder viewHolder, inte position) {
         super.onBindViewHolder(viewHolder, position);

         VHAd holder = (VHAd) viewHolder;

         holder.text.setText("AD " + mItems[position]);

     public void onDetachedFromRecyclerView(RecyclerView recyclerView)

       Release the RecyclerView adapter in app’s activity/fragment onDestroy/onDestroyView method

     public void onDestroyView()
      recyclerView.setAdapter (null);


Your AdSpace is now fully set up and ready to start serving Widespace ads!



Do you have any questions or need further guidance?

Feel free to contact and we’ll do our very best to help you out!

Was this article helpful to you?

L:1 | D:2