Get Started

This guide shows you how to integrate the Google Mobile Ads SDK into a brand new app and use it to display a simple DoubleClick banner ad. It should take you about thirty minutes to complete and will give you a good sense of how the SDK functions within an app. If you're new to Google Mobile Ads, this is a great place to start before moving on to more advanced examples.

No two developers have the same level of experience, so we've added occasional notes like this one for those who are new to Android and Android Studio. If you're an expert, feel free to skip them.

Prerequisites

• Running Android Studio 1.0 or higher
• Developing for Android level 9 or higher

In order to complete the Get Started guide, you need to have Android Studio installed on your development machine. If you don't already have it, see the Android Studio site for instructions on how to download everything you need to get up and running.

If you haven't used Android Studio before, consider running through the First App Tutorial for Android Studio before starting this one.

Create a new project

In this step, you create a brand new project in Android Studio to use for our example. If you don't already have Studio running, go ahead and open it now.

Start the new project wizard

If you see the above welcome screen, select New Project. Otherwise, select File > New Project from the menu. This brings up the new project wizard:

Name your project

Enter "BannerExample" as the app name, and whatever company domain you use for your apps. Android Studio automatically determines a good project location, but feel free to change it if you'd like.

Set the required SDK version

On the next screen, select Phone and Tablet for the form factor and a minimum platform SDK version of 9. That's the minimum version supported by the Google Mobile Ads SDK.

Add your main activity

We're keeping it simple for this example, so on this screen select Blank Activity.

Name your activity

On this screen you have the option of choosing names for the app's activity and its related resources. Use the default names for this example, and just click the Finish button.

Compile your new project

After clicking Finish, you have a working project with a single activity. Try compiling and running it (select Run 'app' from the Run menu). You should see a "Hello world!" message on an otherwise empty gray screen. Don't worry, you'll add some more content in the next steps.

If you're new to developing Android apps, take a look at the tutorials for USB Debugging and Using Virtual Devices. You need to do one of those two things in order to run your new app and see what it looks like.

Configure gradle

To use the Mobile Ads SDK in your project, you first need to reference it as a dependency in your app's build.gradle file. Open BannerExample/app/build.gradle and look for a dependencies section near the bottom.

build.gradle (excerpt)

...
dependencies {
        compile fileTree(dir: 'libs', include: ['*.jar'])
        compile 'com.android.support:appcompat-v7:22.2.0'
        compile 'com.google.android.gms:play-services-ads:8.4.0'
    }
...

Add a line to it like the one in bold above. This instructs gradle to include code from the play-services-ads artifact, which is found in the Google Repository.

You may see a warning message across the top of the Android Studio window indicating that gradle needs to perform a sync. If that's the case, click Sync Now to do so. Gradle will refresh your project's libraries to include the dependency you just added.

If this is the first time you've used the Google Repository, you may also see a message asking you to install it. If that happens, just agree to the install and Android Studio will take care of the download for you.

Once your build.gradle file is modified and everything has synced, try rebuilding your project (Run 'app' in the Run menu) to make sure it compiles correctly. You won't see any changes, but including Google Play services is the first step toward getting ads into your app.

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 have an app with two activities, for example, each displaying a banner, you need two ad units, each with its own ID.

In order 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/app/src/main/res/values/strings.xml.

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">/6499/example/banner</string>
</resources>

Add a new <string> tag with a unique identifier for the ad unit. The Ad Unit ID shown above, /6499/example/banner, is a Google-provided Ad Unit ID of a sample banner ad you can use for testing. You should always use test ads when developing and testing your app. Testing with live production ads can cause you to violate DoubleClick For Publishers policy and could result in a suspension of your account. See the addTestDevice method documentation for information on how to get test ads with your own Ad Unit IDs.

While it's not a requirement, storing your Ad Unit ID values in a resource file is a good practice. As your app grows and your ad publishing needs mature, you will occasionally find that you want to change the ID values. If you make sure they're always in a resource file, you'll never have to search through your code looking for them.

Place a PublisherAdView in your main activity layout

Layout files contain XML definitions for the visual design of things like activities, fragments, and list items. In this step, you'll be modifying the layout file for the main activity so that it includes a PublisherAdView at the bottom. You can add things to an activity progammatically via Java code, but layout files offer better separation of presentation and behavior.

There are only two steps remaining before your app is ready to show an ad. First, you need to modify your main activity's layout to include a PublisherAdView. Open BannerExample/app/src/main/res/layout/activity_main.xml in the editor.

activity_main.xml

<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">

    <TextView android:text="@string/hello_world" android:layout_width="wrap_content"
        android:layout_height="wrap_content" />

    <com.google.android.gms.ads.doubleclick.PublisherAdView
        android:id="@+id/publisherAdView"
        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">
    </com.google.android.gms.ads.doubleclick.PublisherAdView>

</RelativeLayout>

Add these to the XML:

1. An additional namespace used for ads:

   http://schemas.android.com/apk/res-auto
   

2. A new element for your PublisherAdView

You'll be asked to provide layout_width and layout_height. You can set both to wrap_content. In the PublisherAdView tag, set the adSize to BANNER and the adUnitId to @string/banner_ad_unit_id.

If you look at the last parameter in the PublisherAdView tag, you can see that it's called adUnitId. This is the Ad Unit ID that the PublisherAdView uses when requesting ads. In this case, we've given it a reference to the string resource you added in the last step, so the PublisherAdView uses that value.

Load the ad in the MainActivity class

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

Open your MainActivity.java file. It's in the BannerExample/app/src/main/java/ folder, though the exact subdirectory path varies based on the domain you used when creating your project above. 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.doubleclick.PublisherAdRequest;
import com.google.android.gms.ads.doubleclick.PublisherAdView;

public class MainActivity extends ActionBarActivity {

    ...

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

        PublisherAdView mPublisherAdView = (PublisherAdView) findViewById(R.id.publisherAdView);
        PublisherAdRequest adRequest = new PublisherAdRequest.Builder().build();
        mPublisherAdView.loadAd(adRequest);
    }

    ...

}

Make these two changes:

1. Import the PublisherAdRequest and PublisherAdView classes.

2. Add code to find your PublisherAdView in the layout, create a PublisherAdRequest, and then load an ad into the PublisherAdView with it.

Do not use the PublisherAdRequest line shown above if you are testing. Refer to our Targeting page to learn more about using test devices and test device IDs.

Once that's completed, you're finished. You now have a fully functional PublisherAdView in your app's main activity.

Enjoy a freshly loaded ad

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

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

See the finished example on Github

Download BannerExample

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.

I see onPause(), onResume() and onDestroy() in the download. What are these?

These are the PublisherAdView lifecycle methods. These allow you to pause, resume and destroy the webview as appropriate when the user leaves the app (by clicking an ad), returns to the app, or leaves the current 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 PublisherAdRequest.Builder.addTestDevice.