Android

From mkMob Developer Wiki
Jump to: navigation, search

The mkMob Ad SDK 1.0 for Android contains the code necessary to integrate mkMob ads with your application. This SDK is designed to work across all Android platforms with a minimum OS version of 2.3.3



How do I start?

To get started with the integration, perform the following steps:

  1. Sign up as a mkMob Publisher.
  2. Download the mkMob Ad Network SDK for Android by clicking here. This bundle also contains a sample app.
  3. Familiarize yourself with the mkMob Advertising Platform. When you are ready, register your property.
  4. Go to the Publisher section and click the My Properties link in the sidebar. Next, click on your property to get your property ID and Ad Slot ID. Copy these values and use them in the integration code.


Requirements

  • Make sure you have the latest copy of the Android SDK. We recommend that you compile against at least Android v4.4 (set target in project.properties to android-19).
  • The mkMob Android SDK requires a run-time of Android 2.3.3 or later (set android:minSdkVersion to at least 10 in your AndroidManifest.xml). This means you can develop with the latest version of the Android SDK and your app will still run on an earlier Android version (2.3.3 minimum).


Adding the SDK to your Project

Before you can start integrating the actual ad units, you have to add the mkMob SDK into your Android Project. Here's how to do it.

  1. Download the mkMob SDK for Android by following the steps listed above.
  2. Unzip the SDK File and Copy the mkMob_AdSdk_x.x.x.jar file to your project by performing the steps given below.
    1. Create a subdirectory named libs in the root directory of your project. This will already be done for you if you have used Android's activityCreator tool.
    2. Copy the mkMob_AdSdk_x.x.x.jar file into the libs directory.


To add the JAR files to your project, perform the following steps:

  1. Right-click your project from the Package Explorer tab.
  2. Select Properties.
  3. Select Java Build Path from the left navigation area.
  4. Select the Libraries tab from the main window.
  5. Click Add JARs...
  6. Select the mkMob_AdSdk_x.x.x.jar file that you copied earlier to the libs directory.
  7. Click OK to add the mkMob SDK to your Android project.


Setup Google Play Services SDK

The mkMob Android SDK requires the Google Play Services, 4.0 or higher, library to function. This is to comply with the Google Play content guidelines for collecting the advertising identifier. To add the SDK, please follow the official Integration Instructions.


Manifest File Changes

Follow these instructions to make changes to your Android manifest file.

Mandatory Inclusion

The mkMob Android SDK requires the Google Play Services, 4.0 or higher, library to function. This is to comply with the Google Play content guidelines for collecting the advertising identifier. Please see here for more information.

Include the below within the <application> tag.

<meta-data 
         android:name="com.google.android.gms.version"
         android:value="@integer/google_play_services_version" />

Mandatory Activities

Ensure that you add the com.mkmob.ads.sdk.MKInterstitialActivity activity file to your AndroidManifest.xml within the <application> tag.

This activity will be used to display interstitial ads. If you do not want interstitials, it can be omitted.

<activity android:name="com.mkmob.ads.sdk.MKInterstitialActivity"
                  android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"
                  android:hardwareAccelerated="false">
</activity>

Mandatory Permissions

Declare the following permissions in your AndroidManifest.xml file just before the closing </manifest> tag:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />


Banner ads use a small portion of the screen to entice users to "click through" to a richer, full-screen experience such as a website or app store page. This guide shows you how to enable your app to serve a banner ad.

To display banners in your Android app, simply add a com.mkmob.ads.sdk.AdView to your UI.


Adding an AdView

Android apps are composed of View objects. An mkMob AdView is a simple View subclass that displays small HTML5 ads.

The code below shows an Activity that will create and display a banner ad:

/**
 * Copyright (c) www.mkMob.com. All Rights Reserved.
 *
 * Simple Activity that embeds an AdView
 *
 */
 
package com.mkmob.example.ads.banner;
 
import com.mkmob.ads.sdk.AdView;
import com.mkmob.ads.sdk.AdRequest;
 
import android.app.Activity;
import android.os.Bundle;
import android.widget.LinearLayout;
 
public class MainActivity extends Activity {
 
    /** The view to show the ad. */
    private AdView adView;
 
    /** Your property and ad slot IDs */
    private static final String PROPERTY_ID = "INSERT_YOUR_PROPERTY_ID_HERE";
    private static final String AD_SLOT_ID = "INSERT_YOUR_AD_SLOT_ID_HERE";
 
    /** 
     * Called when the activity is first created.
     * 
     * @param savedInstanceState
     */
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
 
        adView = new AdView(this);
        adView.setPropertyID(PROPERTY_ID);
        adView.setAdSlotID(AD_SLOT_ID);
 
        // Add the AdView to the view hierarchy. The view will have no size
        // until the ad is loaded.
        LinearLayout layout = (LinearLayout) findViewById(R.id.linearLayout);
        layout.addView(adView);
 
        // Create an ad request with test mode enabled
        AdRequest adRequest = new AdRequest();
        adRequest.setTestMode(true);
 
        // Start loading the ad in the background.
        adView.loadAd(adRequest);
    }
 
    @Override
    public void onDestroy() {
        super.onDestroy();
        // Destroy the AdView.
        adView.destroyView();
    }
}

The Result

When you run your app, you should see a banner at the top of the screen:
*


Customizing Ad Requests


To allow mkMob to better ads, you can customize the AdRequest before passing it to AdView.loadAd.

Enable or Disable Test Mode

While integrating with the mkMob platform, it is highly recommended that you enable Test Mode. With Test Mode enabled, the platform will return sample ads to assist you with your integration. When you have finished testing, you should disable test mode and enable Live Mode.


Test and Live modes are configured with the setTestMode method of AdRequest.

AdRequest adRequest = new AdRequest();
 
/**
 * Passing a boolean value of true to the method will 
 * enable Test mode.
 */
adRequest.setTestMode(true); //test mode is enabled
 
/**
 * To disable Test mode and enable Live mode, pass a boolean value
 * of false to the method.
 */
adRequest.setTestMode(false); //test mode is disabled, you'll get live ads

NOTE: If setTestMode is not called, the SDK will automatically make requests in test mode. Therefore, always ensure that you call setTestMode(false) when going live.


Passing Demographic Information

Demographic data about the user may be passed to mkMob's Ad Server to assist with ad targeting. Demographic information should be specified in the AdRequest by calling the appropriate method. Please see the table below:

SDK Method

Usage

public void setUserAge(int userAge) User's age in years as an unsigned integer between 14 and 100. Values below 14 will be not be used for targeting due to privacy controls.
public void setGender(char gender) User's gender, if known. Accepted values are AdRequest.GENDER_MALE or AdRequest.GENDER_FEMALE.
public void setKeywords(List<String> keywords) A list of words that will be used to return a contextually targeted ad.

Example code:

AdRequest request = new AdRequest();
 
/** Add some keywords about the user */
ArrayList<String> keywords = new ArrayList<String>();
keywords.add("sports");
keywords.add("football");
request.setKeywords(keywords);
 
/** Set user's age */
request.setUserAge(21);
 
/** Set user's gender */
request.setGender(AdRequest.GENDER_MALE);

Setting the Listener


If you need ad status notifications, you need to pass an object to AdView.setAdListener. The object must extend com.mkmob.ads.sdk.MKBannerListener. MKBannerListener provides a default empty implementation for all of its ad lifecycle events. You only need to override the ad events you wish to implement.

adView.setAdListener(new MKBannerListener() {
    @Override
    public void onAdLoaded() {
 
    }
    @Override
    public void onAdFailedToLoad(int errorCode) {
 
    }
    @Override
    public void onAdOpened() {
 
    }
    @Override
    public void onAdClosed() {
 
    }
    @Override
    public void onAdLeftApplication() {
 
    }
});

The following callbacks are received by the listener:

  • onAdLoaded: Called when an ad is received.
  • onAdFailedToLoad: Called when an ad request failed. The error code is usually one of the following:
    • AdRequest.ERROR_CODE_INTERNAL_ERROR
    • AdRequest.ERROR_CODE_INVALID_REQUEST
    • AdRequest.ERROR_CODE_NETWORK_ERROR
    • AdRequest.ERROR_CODE_NO_FILL
  • onAdOpened: Called when an ad opens an overlay that covers the screen.
  • onAdClosed: Called when the user is about to return to the application after clicking on an ad.
  • onAdLeftApplication: Called when an ad leaves the application (e.g., to go to the browser).


Interstitial Ads

Interstitial ads are full screen ads (either static image or video) that are modal in nature. They appear to users either before the launch of an application or at transition points, such as between game levels, or between the homepage and a unique content page. The richer nature of these ads makes them more expensive and subject to impression constraints.

Interstitial State Flow

Upon request, an interstitial ad can be in one of the following states:

  • init
  • loading
  • ready
  • active
  • unknown

1. The first time MKInterstitial is instantiated, the ad will be in the init state.
2. When a request for loading the ad is made, the ad moves to the loading state.
3. When the ad is ready to be displayed, the ad state changes to ready.
4. At this point, a request for displaying the ad can be made.
5. The ad moves to the active state when it is displayed to the user.
6. When the user closes the ad, the ad moves back to the init state.
7. The interstitial is in the unknown state when its state cannot be determined natively.


Getting an Interstitial Ad

The MKInterstitial class is used to request interstitial ads. Usage is nevertheless very similar to AdView:

  • Import com.mkmob.ads.sdk.MKInterstitial, com.mkmob.ads.sdk.AdRequest and com.mkmob.ads.sdk.MKInterstitialListener
  • Declare the instance
  • Create it, specifying a mkMob Property ID and a distinct Ad Slot ID from any used for banners


Once again, the easiest place to do this is somewhere in your application's Activity.

import com.mkmob.ads.sdk.MKInterstitial;
import com.mkmob.ads.sdk.AdRequest;
import com.mkmob.ads.sdk.MKInterstitialListener;
 
public class MainActivity extends Activity {
 
    private MKInterstitial interstitial;
 
    /** 
     * Called when the activity is first created.
     * 
     * @param savedInstanceState
     */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
 
        // Create the interstitial.
        interstitial = new MKInterstitial(this, "YOUR-PROPERTY-ID", "YOUR-AD-SLOT-ID");
 
        // Create ad request.
        AdRequest adRequest = new AdRequest();
        adRequest.setTestMode(true);
 
        // Begin loading your interstitial.
        interstitial.loadInterstitial(adRequest);
    }
}

Render the interstitial ad after getting the callback onInterstitialLoaded; by calling the following method:

if(interstitial.getState() == MKInterstitial.STATE_READY)
    interstitial.show();

IMPORTANT: Your Ad Slot ID must be of type Interstitial. Ad slots used for banner ads will not give you interstitial ads.
You will need to invoke the loadInterstitial() method again before making a call to show(). Make sure that the current state of the interstitial ad is ready before making the call. Otherwise, an IllegalStateException is generated.

Setting the Interstitial Listener

If you need ad status notification, extend the MKInterstitialListener abstract class and register the instance with MKInterstitial.

interstitial.setAdListener(new MKInterstitialListener() {
    @Override    
    public void onShowInterstitialScreen() {
 
    }
    @Override
    public void onLeaveApplication() {
 
    }
    @Override
    public void onDismissInterstitialScreen() {
 
    }
    @Override
    public void onInterstitialLoaded() {
 
    }
    @Override
    public void onInterstitialFailed(int errorCode) {
 
    }
});

The following callbacks are sent to the listener:

  • onInterstitialLoaded - Interstitial ad loaded successfully.
  • onInterstitialFailed - Interstitial ad request failed. The error code is usually one of the following:
    • AdRequest.ERROR_CODE_INTERNAL_ERROR
    • AdRequest.ERROR_CODE_INVALID_REQUEST
    • AdRequest.ERROR_CODE_NETWORK_ERROR
    • AdRequest.ERROR_CODE_NO_FILL
  • onShowInterstitialScreen - Interstitial ad rendered successfully as full screen.
  • onDismissInterstitialScreen - Interstitial ad closed due to user action such as click on close, or back press, and so on.
  • onLeaveApplication - Called when click on the ad results in exiting the application context.