The AdButler Android SDK allows you to serve ads to your app through AdButler. This includes banner ads, interstitial ads, and VAST/VPAID video ads. AdButler supports MRAID 2.0 banner ads and interstitials.

You can download the Android SDK from our GitHub page.

The SDK includes a tester app that you can use to see an example of implementation, as well as test your AdButler ads in the SDK.

This Android SDK guide contains information about:

1. Installation
2. Implementation.
3. Serving banner ads.
4. Serving interstitial ads.
5. Serving VAST video ads.

Installation

You can include this source code in your project, or build and import the AAR.

Implementation

1. Add permissions to AndroidManifest.xml.

<!-- Required -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Optional but recommended -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

2. Add dependencies to app build.gradle.

implementation project(':adbutler-android-sdk')
implementation 'com.google.android.gms:play-services-ads:16.0.0' ← (may already be present)
implementation 'com.google.code.gson:gson:2.8.2'
implementation 'com.squareup.retrofit2:retrofit:2.1.0'
implementation 'com.squareup.retrofit2:converter-gson:2.1.0'
implementation 'com.squareup.okio:okio:1.11.0'

3. Import required classes to any activity that will create ads.

import com.sparklit.adbutler.AdButler;
import com.sparklit.adbutler.AdListener;
import com.sparklit.adbutler.AdRequest;
import com.sparklit.adbutler.BannerView;
import com.sparklit.adbutler.ErrorCode;
import com.sparklit.adbutler.Positions;
import com.sparklit.adbutler.Interstitial;
import android.app.FragmentManager;

4. Initialize AdButler SDK as early as possible in Main Activity.

AdButler.initialize(this); // 'this' being the context

Serving banner ads

Banner ads are rectangular ads that often redirect users to a destination URL when tapped or clicked. They can be horizontal or vertical. Banners can be MRAID enabled or just standard images.

We highly recommend that you give your zones a fixed size that matches the resolution of your ad's image file. This size will be used to create the frame for the web view. You can also opt to specify the size in code. For more information on zones, read About zones.

Creating a banner fragment

Banners require the use of a fragment because they can have some Activity-like behavior (such as in MRAID ads). To create the fragment, add a placeholder in activity layout.xml.

<FrameLayout android:id="@+id/adbutler_frame"
   android:layout_width="match_parent"
   android:layout_height="match_parent">
   <fragment
       android:name="com.sparklit.adbutler.BannerView"
       android:id="@+id/adbutler_fragment"
       android:layout_height="wrap_content"
       android:layout_width="wrap_content"
       />
</FrameLayout>

Retrieving a banner ad

// get a reference to the fragment  (bannerView should be defined previously)
FragmentManager fm = getFragmentManager();
bannerView = (BannerView)fm.findFragmentById(R.id.adbutler_fragment);

// create an ad request
AdRequest request = new AdRequest(ACCOUNT_ID, ZONE_ID); // your account and zone id
// if you want to set any extra data, add it to the request object.
request.setCoppa(0);
request.setAge(30);
request.setGender(AdRequest.GENDER_MALE);
request.setBirthday(new Date());

// initialize will retrieve the banner, and place it in the fragment.
bannerView.initialize(request, Positions.BOTTOM_CENTER, this, new AdListener() {
   @Override
   public void onAdFetchSucceeded() {
       super.onAdFetchSucceeded();
   }

   @Override
   public void onAdFetchFailed(ErrorCode code) {
       super.onAdFetchFailed(code);
   }

   @Override
   public void onInterstitialDisplayed() {
       super.onInterstitialDisplayed();
   }

   @Override
   public void onAdExpanded(){
       super.onAdExpanded();
   }

   @Override
   public void onAdResized(){
       super.onAdResized();
   }

   @Override
   public void onAdLeavingApplication(){
       super.onAdLeavingApplication();
   }

   @Override
   public void onAdClosed() {
       super.onAdClosed();
   }

   @Override
   public void onAdClicked() {
       super.onAdClicked();
   }
});

Serving interstitial ads

Interstitial ads are full screen ads that are usually configured to appear between content, such as at the end of a game's level or when moving from one game mode to another. Interstitials can be MRAID enabled or just standard images.

Interstitials do not require a fragment.

Retrieving an interstitial ad

interstitial = new Interstitial();
// create an ad request
AdRequest request = new AdRequest(0, 0); // your account and zone id
// if you want to set any extra data, add it to the request object.
request.setCoppa(0);
request.setAge(30);
request.setGender(AdRequest.GENDER_MALE);
request.setBirthday(new Date());

// initialize will fetch the ad, but not display it.  
// in this example we show the ad as soon as it is ready
interstitial.initialize(request, this, new AdListener() {
   @Override
   public void onAdFetchSucceeded() {
       super.onAdFetchSucceeded();
   }

   @Override
   public void onInterstitialReady(){
       super.onInterstitialReady();
        // for demo purposes we show the ad immediately once it’s ready.  You don’t have to do this.
       if(interstitial.isReady){  // you can check if it’s ready any time via this property
           interstitial.show();
       }
   }

   @Override
   public void onAdFetchFailed(ErrorCode code) {
       super.onAdFetchFailed(code);
   }

   @Override
   public void onInterstitialDisplayed() {
       super.onInterstitialDisplayed();
   }

   @Override
   public void onAdExpanded(){
       super.onAdExpanded();
   }

   @Override
   public void onAdResized(){
       super.onAdResized();
   }

   @Override
   public void onAdLeavingApplication(){
       super.onAdLeavingApplication();
   }

   @Override
   public void onAdClosed() {
       super.onAdClosed();
   }

   @Override
   public void onAdClicked() {
       super.onAdClicked();
   }
});

Serving VAST video ads

Video Ad Serving Template (VAST) ads are video ads that are usually configured to appear immediately before (pre-roll), immediately after (post-roll), or at certain points in the actual video content's playback (mid-roll). They require a VASTListener to listen for VAST events.

For more information on VAST ads, read How to create a VAST ad item.

Example VASTListener

    new VASTListener() {
        @Override
        public void onMute() {
            super.onMute();
        }

        @Override
        public void onUnmute() {
            super.onUnmute();
        }

        @Override
        public void onPause() {
            super.onPause();
        }

        @Override
        public void onResume() {
            super.onResume();
        }

        @Override
        public void onRewind() {
            super.onRewind();
        }

        @Override
        public void onSkip() {
            super.onSkip();
        }

        @Override
        public void onPlayerExpand() {
            super.onPlayerExpand();
        }

        @Override
        public void onPlayerCollapse() {
            super.onPlayerCollapse();
        }

        @Override
        public void onNotUsed() {
            super.onNotUsed();
        }

        @Override
        public void onLoaded() {
            super.onLoaded();
        }

        @Override
        public void onStart() {
            super.onStart();
        }

        @Override
        public void onFirstQuartile() {
            super.onFirstQuartile();
        }

        @Override
        public void onMidpoint() {
            super.onMidpoint();
        }

        @Override
        public void onThirdQuartile() {
            super.onThirdQuartile();
        }

        @Override
        public void onComplete() {
            super.onComplete();
        }

        @Override
        public void onCloseLinear() {
            super.onCloseLinear();
        }

        @Override
        public void onClose(){
            // if you pass an orientation to VAST, then reset it here.
            // setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED);
        }

        @Override
        public void onReady(){
            // you can display your VAST ad at any point after this is called.
        }

        @Override
        public void onError(){
            // handle errors
        }
    }

VAST ads must be preloaded. After the ad is loaded and prepared, the onReady() function will be called. You will notice that the play() and pause() functions will be called first. This is because the web view, in which the video will be played, is loaded off screen. This makes for a smoother transition to the ad.

After the onReady() function is called, you can call the display() function on the VAST object to display the ad.

Displaying a VAST ad

    // keep an instance of VASTVideo on your activity class, then intialize it like this:
    // orientation = "none", "portrait", "landscape", or null
    vastVideo = new VASTVideo(context, accountID, zoneID, publisherID, orientation, listener);
    vastVideo.preload();

    // after isReady()
    vastVideo.display();

You will need to do this process each time you want an ad to be displayed so that your impressions will be counted correctly. For more information on impressions and accurate tracking, read Requests vs. Impressions.