Difference between revisions of "A Kindle Fire Amazon Mobile Ads API Example Application"

Latest revision as of 19:59, 27 October 2016

<google>BUY_KINDLE_FIRE</google>

With the basic principles of the Amazon Mobile Ads API covered in the preceding chapter, this chapter will work through the creation of a simple application project intended to show how to display an ad within a Kindle Fire-based Android application.

This tutorial makes the assumption that the Amazon Mobile Ads API has been downloaded and installed onto the development system and that banking and tax information has been entered into the Amazon Mobile App Distribution portal as outlined in Integrating Ads with the Amazon Mobile Ads API.

Creating the AdExample Project

Launch the Eclipse environment and create a new Android Application Project named AdExample consisting of an activity named AdExampleActivity with a corresponding layout named activity_ad_example.

Adding the amazon-ads Library to the Project

Locate the new project within the Eclipse Package Explorer panel, right-click on the project name and select the Properties option from the resulting menu. Within the Properties dialog, select the Java Build Path category from the left hand panel and, within the Libraries tab of the Java Build Path panel, click on the Add External JARs… button. In the JAR selection dialog, navigate to the following location (where <api path> is replaced by the location on your file system where the Amazon Mobile Ads API package was installed in the previous chapter):

<api path>/lib

From within the lib directory, select the amazon-ads-<ver>.jar file (where <ver> is the latest release of the library). Once selected, click on the Open button to add the JAR file to the project. On returning to the properties dialog, click on OK.

Next, the JAR file needs to be added to the libs folder of the project. Within a file browser window, locate the JAR file and drag and drop it onto the libs folder of the project in the Package Explorer panel. When prompted whether to copy or link the library, select the Copy files option.

Adding the Application to the Amazon Mobile App Portal

In order to obtain an application key, the application will need to be registered in the Amazon Mobile App Distribution portal. Log into the portal and click on the green Add New App button located in the lower right hand corner of the home page. This will present the New App Submissions screen, which consists of a set of tabs beginning with the General Information screen. Enter a title for the application and make a selection from the Category menu. With this information entered, save the settings. This should display a summary of the application’s general settings, including the application key assigned by Amazon.

Configuring the Application Manifest File

Using the Eclipse Package Explorer panel, locate and double click on the AndroidManifest.xml file and switch to the XML view. Within this file, add the appropriate permission and activity tags so that the file reads as follows:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.adexample"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission  
            android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission 
            android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission 
            android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission 
            android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="17" />

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <activity
            android:name="com.example.adexample.AdExampleActivity"
            android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity android:name="com.amazon.device.ads.MraidBrowser" 
           android:configChanges="keyboardHidden|orientation"/> 
	  <activity android:name="com.amazon.device.ads.VideoActionHandler" 
           android:configChanges="keyboardHidden|orientation|screenSize"/> </application>
</manifest>

Modifying the User Interface Layout

For the purposes of this example, the ad will be created and displayed in the code of the activity rather than via the layout XML file. Before writing the Java code to achieve this, however, some slight changes need to be made to the activity_ad_example.xml file. Locate this file in the Package Explorer panel and double click on it to load it into the Graphical Layout tool. Once it has loaded, select and delete the “Hello World” TextView object.

Next, right-click on the layout background, select the Change Layout… menu option and use the resulting dialog to change the layout type to LinearLayout (Vertical).

Implementing the AdListener

In order to receive event notifications from the AdLayout view, it is necessary to declare a listener class. In order to make the AdExampleActivity class act as the listener for this application, locate and edit the AdExampleActivity.java file and modify it as follows:

package com.example.adexample;

import com.amazon.device.ads.AdError;
import com.amazon.device.ads.AdLayout;
import com.amazon.device.ads.AdListener;
import com.amazon.device.ads.AdProperties;

import android.os.Bundle;
import android.app.Activity;
import android.util.Log;
import android.view.Menu;

public class AdExampleActivity extends Activity implements AdListener {

	
	
	private static final String TAG = "com.example.adexample";

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		
		AdLayout myAdView;
		
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_ad_example);
	}

	@Override
	public boolean onCreateOptionsMenu(Menu menu) {
		getMenuInflater().inflate(R.menu.activity_ad_example, menu);
		return true;
	}

	@Override
	public void onAdCollapsed(AdLayout adLayout) {
		Log.i(TAG, "Ad collapsed");
	}

	@Override
	public void onAdExpanded(AdLayout adLayout) {
		Log.i(TAG, "Ad expanded");
	}

	@Override
	public void onAdFailedToLoad(AdLayout adLayout, AdError adError) {
		Log.i(TAG, "Ad failed to load");
	}

	@Override
	public void onAdLoaded(AdLayout adLayout, AdProperties adProperties) 	{
		Log.i(TAG, "Ad loaded successfully");
	}
} 

Modifying the onCreate() Method

The remainder of the work to display the ad is going to be performed within the onCreate() method of the activity class. This method needs to perform the following tasks:

1. Register the application key with the API.

2. Create an AdLayout instance configured for the required ad size.

3. Set the enclosing activity class as the listener for the AdLayout instance.

4. Obtain a reference to the LinearLayout view in the user interface.

5. Add the AdLayout instance to the LinearLayout view with appropriate layout parameters.

6. Enable ad API testing and logging modes for the application.

7. Create an AdTargetingOptions instance.

8. Instruct the AdLayout instance to load an ad. Bringing the above requirements together results in a modified onCreate() method in the AdExampleActivity.java file which reads as follows (where <your app key here> is replaced by the application key generated by the Amazon Mobile App Distribution portal):

package com.example.adexample;

import com.amazon.device.ads.AdError;
import com.amazon.device.ads.AdLayout;
import com.amazon.device.ads.AdListener;
import com.amazon.device.ads.AdProperties;
import com.amazon.device.ads.AdRegistration;
import com.amazon.device.ads.AdTargetingOptions;

import android.os.Bundle;
import android.app.Activity;
import android.util.Log;
import android.view.Menu;
import android.widget.LinearLayout;

public class AdExampleActivity extends Activity implements AdListener {
	
	private static final String TAG = "com.example.adexample";

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		
		AdLayout myAdView;

		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_ad_example);
		
		AdRegistration.setAppKey(getApplicationContext(),
			    "<your app key here>");
		   
		myAdView = new AdLayout(this, AdLayout.AdSize.AD_SIZE_600x90);
		myAdView.setListener(this);
		
		LinearLayout layout = 
               (LinearLayout) findViewById(R.id.LinearLayout1);
		  
		LinearLayout.LayoutParams params = 
                new LinearLayout.LayoutParams(
		       LinearLayout.LayoutParams.WRAP_CONTENT,
		       LinearLayout.LayoutParams.WRAP_CONTENT);

		layout.addView(myAdView,params);
		    
		AdRegistration.enableTesting(this, true);
		AdRegistration.enableLogging(this, true);
		    
		AdTargetingOptions adOptions = new AdTargetingOptions();	
		myAdView.loadAd(adOptions);
	}
.
.
}

Testing the Application

With the changes to the project complete, compile and run the application on either a physical Kindle Fire device or a suitably configured emulator. Once the application has loaded, an ad should appear on the screen (Figure 46-1). In the event that an ad does not appear, check the LogCat output for any error reports. In the event that the ad appears, interacting with it should cause the diagnostic messages from the listener callback methods to also appear within the LogCat panel.

Figure 46 1

Summary

This chapter has worked through the creation of a simple application project that does nothing more than display a single ad to the user. In this example, the ad was created using code. Keep in mind when placing ads within an XML layout file that the Amazon namespace must be included in the XML and that the amazon_ads_attrs.xml file must be added to the res/values folder of the project as outlined in Integrating Ads with the Amazon Mobile Ads API.

<google>BUY_KINDLE_FIRE</google>