Set Up Google Play Services SDK

To develop an app using the Google Play services APIs, you must download the Google Play services SDK from the SDK Manager. The download includes the client library and code samples.

To test your app when using the Google Play services SDK, you must use either:

  • A compatible Android device that runs Android 2.3 or higher and includes Google Play Store.
  • The Android emulator with an AVD that runs the Google APIs platform based on Android 4.2.2 or higher.

Ideally, you should develop and test your app on a variety of devices, including both phones and tablets.

Install the Google Play Services SDK

To install the Google Play services SDK for development:

  1. Launch the SDK Manager in one of the following ways:
    • In Android Studio, click SDK Manager in the toolbar.
    • In Eclipse (with ADT), select Window > Android SDK Manager.
    • On Windows, double-click the SDK Manager.exe file at the root of the Android SDK directory.
    • On Mac or Linux, open a terminal and navigate to the tools/ directory in the Android SDK, then execute android sdk.
  2. Install the Google Play services SDK.

    Scroll to the bottom of the package list, expand Extras, select Google Play services, and install it. If you're using Android Studio, also install Google Repository (it provides the Maven repository used for Gradle builds).

    The Google Play services SDK is saved in your Android SDK environment at <android-sdk>/extras/google/google_play_services/.

    Note: Google Play services 4.0.30 (released November 2013) and newer versions require Android 2.3 or higher. If your app supports Android 2.2, you can continue development with the Google Play services SDK, but must instead install Google Play services for Froyo from the SDK Manager.

  3. Install a compatible version of the Google APIs platform.

    If you want to test your app on the emulator, expand the directory for Android 4.2.2 (API 17) or a higher version, select Google APIs, and install it. Then create a new AVD with Google APIs as the platform target.

  4. Make a copy of the Google Play services library project.

    Note: If you are using Android Studio, skip this step.

    Copy the library project at <android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/ to the location where you maintain your Android app projects.

    If you are using Eclipse, import the library project into your workspace. Click File > Import, select Android > Existing Android Code into Workspace, and browse to the copy of the library project to import it.

Set Up a Project that Uses Google Play Services

Using Android Studio:

  1. Open the build.gradle file inside your application module directory.

    Note: Android Studio projects contain a top-level build.gradle file and a build.gradle file for each module. Be sure to edit the file for your application module.

  2. Add a new build rule under dependencies for the latest version of play-services. For example:
    apply plugin: 'android'
    ...
    
    dependencies {
        compile 'com.android.support:appcompat-v7:+'
        compile 'com.google.android.gms:play-services:4.3.23'
    }
    

    Be sure you update this version number each time Google Play services is updated.

  3. Save the changes and click Sync Project with Gradle Files in the toolbar.
  4. Open your app's manifest file and add the following tag as a child of the <application> element:
    <meta-data android:name="com.google.android.gms.version"
               android:value="@integer/google_play_services_version" />
    

You can now begin developing features with the Google Play services APIs.

Using Eclipse or another IDE:

To make the Google Play services APIs available to your app, you must reference the library project you created in step 4 of the installation instructions.

See the Referencing a Library Project for Eclipse or Referencing a Library Project on the Command Line for more information on how to do this.

Note: You should be referencing a copy of the library that you copied to your development workspace—you should not reference the library directly from the Android SDK directory.

After you've added the Google Play services library as a dependency for your app project, open your app's manifest file and add the following tag as a child of the <application> element:

<meta-data android:name="com.google.android.gms.version"
           android:value="@integer/google_play_services_version" />

Once you've set up your project to reference the library project, you can begin developing features with the Google Play services APIs.

Create a Proguard Exception

To prevent ProGuard from stripping away required classes, add the following lines in the <project_directory>/proguard-project.txt file:

-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}

-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
    public static final *** NULL;
}

-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
    @com.google.android.gms.common.annotation.KeepName *;
}

-keepnames class * implements android.os.Parcelable {
    public static final ** CREATOR;
}

Note: When using Android Studio, you must add Proguard to your gradle.build file's build types. For more information, see the Gradle Plugin User Guide.

Ensure Devices Have the Google Play services APK

As described in the Google Play services introduction, Google Play delivers service updates for users on Android 2.3 and higher through the Google Play Store app. However, updates might not reach all users immediately, so your app should verify the version available before attempting to perform API transactions.

Important: Because it is hard to anticipate the state of each device, you must always check for a compatible Google Play services APK before you access Google Play services features. For many apps, the best time to check is during the onResume() method of the main activity.

The Google Play services library includes utility methods that help you determine whether or not the Google Play services version on the device supports the version of the client library you are using. If the version on the device is too old, the system will take the user to Google Play Store in order to install the recent version of the Google Play services.

Because each app uses Google Play services differently, it's up to you decide the appropriate place in your app to check verify the Google Play services version. For example, if Google Play services is required for your app at all times, you might want to do it when your app first launches. On the other hand, if Google Play services is an optional part of your app, you can check the version only once the user navigates to that portion of your app.

To verify the Google Play services version, call isGooglePlayServicesAvailable(). If the result code is SUCCESS, then the Google Play services APK is up-to-date and you can continue to make a connection. If, however, the result code is SERVICE_MISSING, SERVICE_VERSION_UPDATE_REQUIRED, or SERVICE_DISABLED, then the user needs to install an update. So, call GooglePlayServicesUtil.getErrorDialog() and pass it the result error code. This returns a Dialog you should show, which provides an appropriate message about the error and provides an action that takes the user to Google Play Store to install the update.

To then begin a connection to Google Play services, read Accessing Google Play Services APIs.