Android Advertiser SDK

Millennial Media Android Advertiser SDK - Version 4.5.0

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

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 network and their own custom branded apps. The Advertiser SDK creates this link by enabling your custom branded app to show a transitional overlay when launched by an advertisement shown in another third-party app. It also allows you to do track conversions, or the number of users who downloaded your app as a result of an advertisment. You should use the Advertiser SDK in your app instead of the Developer SDK because the Developer SDK does not have the capability of showing transitional overlays. The Advertiser SDK is also much smaller than the Developer SDK.

The remainder of 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 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 do not hesitate to reach out to AdvertiserSDK@millennialmedia.com. Please include the platform you are developing for.

Contents of the Zip File

• Readme.pdf (this file)
• License.txt
• Changelog.txt
• MMBrandedSDK.jar
  • The library containing Millennial Media Branded classes and resources to include in your app

• SampleBrandedApp/
  • A barebones sample application that demonstrates basic MMBranded 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 and the Javadocs folder.

1. Download the Android Advertiser SDK here: http://bit.ly/AndroidAdvertiserSDK
2. Place the MMBrandedSDK.jar into the libs directory of your Android project.
3. Add MMBrandedSDK.jar to your project’s build path.
4. In your AndroidManifest.xml file add the following:
   • Permissions for android.permission.INTERNET, android.permission.READ_PHONE_STATE, and android.permission.ACCESS_NETWORK_STATE.
   • Activity for com.millennialmedia.android.MMBrandedOverlayActivity with attribute: android:configChanges="keyboardHidden|orientation|keyboard".

1. Edit your entry for your app’s main activity in the AndroidManifest.xml file by adding an intent filter with android.intent.action.VIEW, android.intent.category.DEFAULT, android.intent.category.BROWSABLE and the data scheme <data android:scheme=yourscheme
2. In your main activity’s onCreate method detect if the Intent used to launch your app has data attached to it. If it does it 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, MMBrandedSDK.reportConversionWithGoalId() and MMBrandedSDK.parseUri() respectively.

What’s New In This Version

• The whole thing! This is our first release of the Android Advertiser SDK.

Documentation

Add the Millennial Media Library

• Place the MMBrandedSDK.jar file in the libs directory of your project.
• If you are using Eclipse, add MMBrandedSDK.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 MMBrandedSDK.jar file.
• Highlight MMBrandedSDK.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 <manifest></manifest> 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 single activity for displaying overlays. Overlays in a branded app allow users to transition from an ad displayed in another app to using your app that they already have installed. Inside the <application></application> tags add the following activity code:

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

Using the SDK

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

Uri launchUri = this.getIntent().getData();
if(this.getIntent().getData() != null)
{
    // Begin conversion tracking
    MMBrandedSDK.reportConversionWithGoalId(this, "12345");

    // 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");
    MMBrandedSDK.setInfo(info);

    // Have the Advertiser SDK look at the uri and open an overlay if needed
    HashMap<String,String> params = MMBrandedSDK.parseUri(this, launchUri);

    // Use the returned HashMap
    StringBuilder stringBuilder = new StringBuilder("Welcome to Millennial Media's sample branded 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 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 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 Millennial Media’s system that your app had been launched and could potentially be counted as an campaign-driven conversion. The first argument is a reference to a valid Activity running in your app. The second argument is the goalId setup with Millennial Media to track downloads of your app.

Overlay Information

The setInfo(HashMap&lt;String, Object&gt; 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().