Millennial Media Android Advertiser SDK - Version 4.6

Included here are all of the resources for integrating the Millennial Media Android Advertiser SDK into your application.

Introduction

The Millennial Media Android Advertiser SDK is a Java-based library that allows advertisers to create a powerful link between ads running on Millennial Media’s platform and their own custom advertiser apps. The Advertiser SDK enables apps to show a transitional overlay when launched by an advertisement shown in another third-party app. Additionally, it allows advertisers to track the number of users who downloaded your app, or completed another action as a result of an advertisement.

This document covers integrating the Advertiser SDK into your app and writing code to accept incoming data from ads running on the network. It is written for developers and product managers with the assumption they are familiar with Android development, Eclipse, Java, the Android Development Tools (ADT), and Android Virtual Devices.

If you have any questions during the implementation of the Advertiser SDK, please contact us at AdvertiserSDK@millennialmedia.com and tell us which development platform you are using.

What’s New In This Version

  • Added support for Android 4.0 (Ice Cream Sandwich).
  • General bug fixes.
  • Deprecated MMAdViewOverlayActivity and introduced MMActivity.

Contents of the Zip File

  • Readme.pdf
  • License.txt
  • Changelog.txt
  • MMAdvertiserSDK.jar - The library containing Millennial Media Advertiser classes and resources to include in your app.
  • SampleAdvertiserApp/ - A sample application that demonstrates basic MMAdvertiser integration.
  • Javadocs/ - HTML files containing Javadocs documentation for public classes and methods.

Quick Start

For a short overview, or if you have used the Millennial Media Android Developer SDK in the past, you can reference the quick start instructions below. If you would like more detailed information, please see the detailed documentation in this document.

Step 1: Download the Android Advertiser SDK.

| Download the Android Advertiser SDK here: http://bit.ly/Android_Advertiser_SDK_v4_6 | |———————————————————————————————————————————-|

Step 2: Place MMAdvertiserSDK.jar into the libs directory of your Android project.

Step 3: Add MMAdvertiserSDK.jar to your project’s build path.

Step 4: Add the following to your AndroidManifest.xml file.

  • Permissions for android.permission.INTERNET, android.permission.READ_PHONE_STATE, and android.permission.ACCESS_NETWORK_STATE.
  • Activity for com.millennialmedia.android.MMAdvertiserOverlayActivity with attribute: android:configChanges=”keyboardHidden orientation keyboard”.

Step 5: Edit your entry for your app’s main activity in the AndroidManifest.xml file.

Add an intent filter with android.intent.action.VIEW, android.intent.category.DEFAULT, android.intent.category.BROWSABLE and the data scheme with data android:scheme=yourscheme.

Step 6: In your main activity’s onCreate method, detect if the Intent used to launch your app has data attached to it.

If it does, this may have come from a creative on Millennial Media’s network. You can then use our Advertiser SDK to do conversion tracking and process the launch data, MMAdvertiserSDK.reportConversionWithGoalId() and MMAdvertiserSDK.parseUri(), respectively.

Documentation

Add the Millennial Media Library

  • Place the MMAdvertiserSDK.jar file in the libs directory of your project.
  • If you are using Eclipse, add MMAdvertiserSDK.jar to your application’s build path.
  • Highlight your project in the package explorer.
  • Press ALT+ENTER to bring up the properties dialog.
  • Click “Java Build Path”.
  • Select the Libraries Tab.
  • Click “Add External JARs…”.
  • Browse to the location of the MMAdvertiserSDK.jar file.
  • Highlight MMAdvertiserSDK.jar and select the “Open” button.
  • Select “OK”/

Set the Permissions and Configurations in the Manifest File

The SDK relies on having an active Internet connection to display overlays. Before the SDK can show overlays, necessary permissions must first be added to your AndroidManifest.xml file. If you are in Eclipse, follow the instructions below; otherwise just open your AndroidManifest.xml file in a text editor.

  • Highlight your AndroidManifest.xml file in the project explorer.
  • Double-click on the file or press F3 to open it.
  • Click on the AndroidManifest.xml tab to reveal the raw XML source.

Inside the main activity for you app, add the following intent filter:

<intent-filter> <action android:name="android.intent.action.VIEW" /> 
    <category android:name="android.intent.category.DEFAULT" /> 
    <category android:name="android.intent.category.BROWSABLE" /> 
    <data android:scheme="yourscheme" /> 
</intent-filter>

Inside the element add the following code:

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

The SDK implements a single activity for displaying overlays. Overlays in a advertiser app allow users to transition from an ad displayed in another app to using your app that they already have installed.

Add the following activity code inside the tags:

<activity android:name="com.millennialmedia.android.MMAdvertiserOverlayActivity" 
      android:configChanges="keyboardHidden|orientation|keyboard" >
</activity>

The content blocks below show the changes that are required to properly integrate the Advertiser SDK into your application.

Ad SDK Manifest Example

Using the SDK

The code presented below, taken directly from the sample advertiser app project, demonstrates the three methods available to use in the Advertiser SDK.

@Override
public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    
    // Begin conversion tracking
    MMAdvertiserSDK.trackConversion(this, "12345");
	
    Uri launchUri;
    if((launchUri = this.getIntent().getData()) != null)
    {
    
    	// Set any info you want to pass to the overlay
    	HashMap<String, Object> info = new HashMap<String, Object>();
    	info.put("age", new Integer(20));
    	info.put("school", "Stanford University");
    	MMAdvertiserSDK.setInfo(info);
    	
    	// Have the advertiser app SDK look at the uri and open an overlay if needed
    	HashMap<String,String> params = MMAdvertiserSDK.parseUri(this, launchUri);
    	
    	// Use the returned HashMap
    	StringBuilder stringBuilder = new StringBuilder("Welcome to Millennial Media's sample advertiser app.\n\n");
    	for(String key : params.keySet())
    	{
    		stringBuilder.append(String.format("%s: %s\n", key, params.get(key)));
    	}        	
    	TextView textView = (TextView)findViewById(R.id.textView);
    	textView.setText(stringBuilder.toString());
    }
}

When implementing an activity, you can inspect the intent for a Uniform Resource Identifier (URI) in the getData() method. If you do have a URI, then this means that your app was launched using the scheme that was specified in the AndroidManifest.xml file.

After confirming the presence of a URI, you can use the Advertiser SDK in the three ways highlighted below.

All of the methods provided below should be used inside the onCreate(Bundle savedInstanceState) method of your main Activity.

Conversion Tracking

The reportConversionWithGoalId(Activity activity, String goalId) method allows your app to report to our system that your app had been launched and could potentially be counted as a campaign-driven conversion.

  • The first argument is a reference to a valid Activity running in your app.
  • The second argument is the App Tracking ID setup with Millennial Media to track downloads of your app.

Overlay Information

The setInfo(HashMap <String, Object> newInfo) method allows you to pass an arbitrary HashMap of values to the Advertiser SDK. These values are only used when an overlay is shown as part of the launch process. These values will only be meaningful to and shared with your custom transitional overlay.

Overlays and Parsing the Launch Uri

When launching your app from an advertisment in a third-party app, you may choose to show an overlay at launch. An overlay may create a more seemless transition for your users. This can be controlled by your settings in the campaign portal.

The HashMap<String,String> parseUri(Activity activity, Uri uri) method provides a convenient way of parsing all the launch parameters into a HashMap and is also responsible for launching any overlay that has been configured.

  • The first argument to parseUri is a reference to a valid Activity running in your app.
  • The second argument is the Uri obtained from getData().

Android Overlay Example

For More Information