Get Started in Eclipse

This guide shows you how to use Eclipse to integrate the Google Mobile Ads SDK into a brand new app and display a simple banner ad. It takes about thirty minutes to complete and provides a good sense of how the SDK functions within an app.

The ad unit and samples that we provide return test ads. Test ads are always available, even if your account is suspended or disabled. For more information, review the AdMob policies and learn more about invalid activity.

It is against AdMob policy to click on your own live ads. During development and testing, use only test ads. If you do need to render live ads before launch, avoid clicking on them. If you click on live ads, your AdMob account may be suspended.

The guide is intended for developers who are familiar with Eclipse and have already used it to create Android apps. If you're new to Android coding, consider getting started with Android Studio. It's the official IDE for Android development.

No two developers have the same level of experience, so we've added occasional notes like this one for those who would like a little extra info. If you're an expert Android developer, feel free to skip them.

Prerequisites

Create a new project

This procedure steps you through the process of creating a brand new project in Eclipse to use for our example.

  1. Open Eclipse with an empty workspace and choose File > New > Project from the menu.

  2. Select the Android folder, choose Android Application Project, and click Next to select a wizard.

  3. Create your project. Enter "BannerExample" in the Application Name and Project Name fields. Enter whatever package name you normally use in the Package Name field. Select version 9—the minimum version supported by the Google Mobile Ads SDK—and click Next.

  4. Configure your new project. We're keeping it simple here, so uncheck the Create custom launcher icon check box and click Next. Everything else can stay as it is.

  5. Create an activity. Check the Create Activity check box and select Blank Activity on the list if they haven't been already.

  6. Name your activity. Here again, the default options are what you need. Just click Finish and Eclipse creates your new project's source code.

Compile your new project

Once Eclipse is finished, try compiling and running your new app. The system displays a "Hello world!" message on a gray screen. Don't worry, we'll add some more content in the next steps.

Download the Google Play services SDK

The Google Play services SDK contains classes and resources that your app can use to request and display ads. Update the IDE and Tools to ensure that you have the latest version of the SDK Manager. You can do this by selecting Window > Android SDK Manager.

The SDK Manager

In the Android SDK Manager window, select Google Play services in the Extras folder, then press Install packages and accept the licenses to download. If Install packages is disabled, don't worry. That just means you already have the latest version, so there's nothing else you need to do in the SDK Manager.

Include the Google Play services library

Now that the Google Play services SDK is downloaded, you can reference it in your project. Select File > New > Project from the menu.

Create a project from existing code

Select the Android folder and then Android Project from Existing Code within it.

Import projects

Now you just need to tell Eclipse where it can find the library. Click Browse, navigate to /extras/google/google_play_services/libproject/google-play-services_lib/, and click OK. When the browse dialog closes, the system displays a Projects list with a single item. Make sure the check box next to the item is checked, then click Finish to create a new project with the imported code.

Reference the imported project

With the new project created, you can reference it in your app's code. Right-click BannerExample in the Package Explorer and select Properties.

Properties for BannerExample

Select Android in the list of property sections on the left, click Add, then click OK.

Project selection

You'll see google-play-services_lib in the list view. Choose it, then click OK to close the selection dialog, and again to close the properties dialog. Your app now contains a reference to the Google Play services library project, which means it can use the classes and resources contained in the Google Play services SDK.

Try building and running your app again to make sure everything is correctly in place. You won't see any changes, but including Google Play services is the first step toward getting ads into your app.

Modify the manifest file

Now that you have a working app that includes Google Play services, it's time to modify the app manifest file to include the permissions, version number, and activity definition that the Mobile Ads SDK requires. Open the Android manifest for the BannerExample project, AndroidManifest.xml, for editing. The file is in the BannerExample/src/ folder. (The exact path may differ if you choose another package name path when setting up the project.)

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.google.android.gms.example.bannerexample" >

    <uses-sdk
        android:minSdkVersion="9"
        android:targetSdkVersion="21" />

    <!-- Include required permissions for Google Mobile Ads to run-->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <!--This meta-data tag is required to use Google Play services.-->
        <meta-data android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />
        <activity
            android:name=".MainActivity"
            android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <!--Include the AdActivity configChanges and theme. -->
        <activity android:name="com.google.android.gms.ads.AdActivity"
            android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"
            android:theme="@android:style/Theme.Translucent" />
    </application>

</manifest>

You need to make three changes :

  • Add two <uses-permission> tags for INTERNET and ACCESS_NETWORK_STATE. The tag for INTERNET is required and used to access the Internet to make ad requests. ACCESS_NETWORK_STATE is optional and used to check if an Internet connection is available prior to making an ad request.

  • Add a <meta-data> tag that references the Google Play services version. This lets Android know which version of the service your app expects to use.

  • Add an <activity> element with configChanges and theme attributes. This activity is used by the SDK when banner ads are clicked or interstitial ads are presented, and like any other activity, must be declared in the manifest before being presented.

Go ahead and rebuild the project to make sure everything has been done correctly. The system displays the same "Hello world!" message for now. But configuring the app manifest file correctly enables your app to use Mobile Ads.

Give your app an ad unit ID

An ad unit ID is a unique identifier given to the places in your app where ads are displayed. If you had an app with two activities, for example, each displaying a banner, you'd have two ad units, each with its own ID. AdMob ad unit IDs have the form ca-app-pub-XXXXXXXXXXXXXXXX/NNNNNNNNNN.

For your new app to display an ad, it needs to include an ad unit ID. Open your app's string resource file, which is found at BannerExample/res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">My Application</string>
    <string name="hello_world">Hello world!</string>
    <string name="action_settings">Settings</string>
    <string name="banner_ad_unit_id">ca-app-pub-3940256099942544/6300978111</string>
</resources>

Add a new <string> tag as shown. Note that the ad unit ID provided above is just for testing. It allows you to retrieve a sample banner ad and make sure your implementation is correct.

It is against AdMob policy to click on your own live ads. During development and testing, use only test ads. If you do need to render live ads before launch, avoid clicking on them. If you click on live ads, your AdMob account may be suspended.

See the addTestDevice() method documentation for information on how to get test ads with your own ad unit IDs.

Place an AdView in your main activity layout

You have three more steps to complete before your app is ready to show an ad:

  1. Open BannerExample/res/layout/activity_main.xml in the editor:

    <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent"
        xmlns:ads="http://schemas.android.com/apk/res-auto"
        android:layout_height="match_parent" android:paddingLeft="@dimen/activity_horizontal_margin"
        android:paddingRight="@dimen/activity_horizontal_margin"
        android:paddingTop="@dimen/activity_vertical_margin"
        android:paddingBottom="@dimen/activity_vertical_margin"
        tools:context=".MainActivity">

    &lt;TextView android:text="@string/hello_world" android:layout_width="wrap_content"
        android:layout_height="wrap_content" /&gt;</span>
    
    <span class="newcode">&lt;com.google.android.gms.ads.AdView
        android:id="@+id/adView"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:layout_alignParentBottom="true"
        ads:adSize="BANNER"
        ads:adUnitId="@string/banner_ad_unit_id"&gt;
    &lt;/com.google.android.gms.ads.AdView&gt;</span>
    

    </RelativeLayout>

  2. Add an additional namespace, http://schemas.android.com/apk/res-auto, to use for ads.

  3. Add a new element for your AdView. The system prompts you to provide layout_width and layout_height. You can set these both to wrap_content. In the AdView tag, set the adSize to BANNER and the adUnitId to @string/banner_ad_unit_id.

Load the ad in the MainActivity class

The last change needed is for you to add some Java code to your app's main activity class for loading an ad into the AdView.

Open your MainActivity.java file. The file is in the BannerExample/src/ folder. (The exact path may differ if you chose another package name path when setting up the project.) Once it's open in the editor, look for the onCreate() method in the MainActivity class:

MainActivity.java (excerpt)

package ...

import ...
import ...
import com.google.android.gms.ads.AdRequest;
import com.google.android.gms.ads.AdView;

public class MainActivity extends ActionBarActivity {

    ...

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        AdView mAdView = (AdView) findViewById(R.id.adView);
        AdRequest adRequest = new AdRequest.Builder().build();
        mAdView.loadAd(adRequest);
    }

    ...

}

To get a fully functional AdView in your app's main activity, make these changes:

  • Import the AdRequest and AdView classes.

  • Add the code to find your AdView in the layout, create an AdRequest, and then load an ad into the AdView with it.

Once that's completed, you're finished.

Enjoy a freshly loaded ad

Your app is now ready to display an ad using the Google Mobile Ads SDK. Run it again, and the system displays a test banner at the bottom of the device screen:

Congratulations! You've successfully integrated banner ads into an app with Eclipse.

FAQ

My app doesn't show an ad when I run it, and I see "Not enough space to show ad" in the log—what's going on?
It sounds like you're testing the app on a device with a screen that's 320dp wide. With the default padding for the activity (16dp), there's not enough space to show a 320x50 test banner. Try removing the android:paddingRight and android:paddingLeft attributes from the RelativeLayout in activity_main.xml, and then recompiling the app.
Do I need to use test ads?
Yes. It is against AdMob policy to click on your own live ads. During development and testing, use only test ads. If you do need to render live ads before launch, avoid clicking on them. If you click on live ads, your AdMob account may be suspended. For more information, review the AdMob policies and learn more about invalid activity.
How do I get test ads?
The ad unit and samples that we provide return test ads. You can also request test ads by using AdRequest.Builder.addTestDevice().
How do I get an AdMob ad unit ID?
Create an ad unit describes the entire process. AdMob ad unit IDs have the form ca-app-pub-XXXXXXXXXXXXXXXX/NNNNNNNNNN.

Send feedback about...

AdMob by Google
AdMob by Google