android_frameworks_base/docs/html/google/play-services/setup.jd

page.title=Setting Up Google Play Services
@jd:body



<div id="qv-wrapper">
<div id="qv">

<h2>In this document</h2>
<ol>
  <li><a href="#Setup">Add Google Play Services to Your Project</a></li>
  <li><a href="#Proguard">Create a Proguard Exception</a></li>
  <li><a href="#ensure">Ensure Devices Have the Google Play services APK</a></li>
</ol>


</div>
</div>

<script>
$(document).ready(function() {
  setupIdeDocToggle();
});
</script>


<p>To develop an app using the <a href="{@docRoot}reference/gms-packages.html">Google
Play services APIs</a>, you need to set up your project with the Google Play services SDK.
<p>If you haven't installed the Google Play services SDK yet, go get it now by following the guide
to <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</a>.</p>

<p>To test your app when using the Google Play services SDK, you must use either:</p>
<ul>
  <li>A compatible Android
    device that runs Android 2.3 or higher and includes Google Play Store.</li>
  <li>The Android emulator with an <a href="{@docRoot}tools/devices/index.html">AVD</a>
  that runs the Google APIs platform based on Android 4.2.2 or higher.</li>
</ul>



<h2 id="Setup">Add Google Play Services to Your Project</h2>

<p>
<select class="ide">
  <option value="eclipse">Using Eclipse with ADT</option>
  <option value="studio">Using Android Studio</option>
  <option value="other">Using something else</option>
</select>
</p>


<div class="select-ide studio">
<p>To make the Google Play services APIs available to your app:</p>
<ol>
  <li>Open the <code>build.gradle</code> file inside your application module directory.
      <p class="note"><strong>Note:</strong> Android Studio projects contain a top-level
      <code>build.gradle</code> file and a <code>build.gradle</code> file for each module.
      Be sure to edit the file for your application module. See
      <a href="{@docRoot}sdk/installing/studio-build.html">Building Your Project with
      Gradle</a> for more information about Gradle.</p></li>
  <li>Add a new build rule under <code>dependencies</code> for the latest version of
<code>play-services</code>. For example:
<pre class="no-pretty-print">
apply plugin: 'android'
...

dependencies {
    compile 'com.android.support:appcompat-v7:20.+'
    <strong>compile 'com.google.android.gms:play-services:5.+'</strong>
}
</pre>
<p>Be sure you update this version number each time Google Play services is updated.</p>
  </li>
  <li>Save the changes and click <strong>Sync Project with Gradle Files</strong>
<img src="{@docRoot}images/tools/sync-project.png" style="vertical-align:bottom;margin:0;height:19px" />
in the toolbar.
  </li>
  <li>Open your app's manifest file and add the following tag as a child of the <a
href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application>}</a>
element:
<pre>
&lt;meta-data android:name="com.google.android.gms.version"
           android:value="&#64;integer/google_play_services_version" />
</pre>
  </li>
</ol>

<p>You can now begin developing features with the
<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>

</div><!-- end studio -->

<div class="select-ide eclipse">

<p>To make the Google Play services APIs available to your app:</p>
<ol>
  <li>Copy the library project at <code>&lt;android-sdk&gt;/extras/google/google_play_services/libproject/google-play-services_lib/</code> to the location where you maintain your Android app projects.</li>
  <li>Import the library project into your Eclipse workspace. Click
    <b>File > Import</b>, select <b>Android > Existing Android Code into
Workspace</b>, and browse to the copy of the library project to import it.</li>
  <li>In your app project, reference Google Play services library project. See
    <a href="{@docRoot}tools/projects/projects-eclipse.html#ReferencingLibraryProject">Referencing a Library Project for Eclipse</a> for more information on how to
    do this.
  <p class="note"><strong>Note:</strong> You should be referencing a copy of the
    library that you copied to your development workspace&mdash;you should not
    reference the library directly from the Android SDK directory.</p>
  </li>
  <li>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
    <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application>}</a>
element:
    <pre>
&lt;meta-data android:name="com.google.android.gms.version"
        android:value="&#64;integer/google_play_services_version" />
    </pre>
  </li>
</ol>

<p>Once you've set up your project to reference the library project,
you can begin developing features with the
<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>

</div><!-- end eclipse -->

<div class="select-ide other">

<p>To make the Google Play services APIs available to your app:</p>
<ol>
  <li>Copy the library project at <code>&lt;android-sdk&gt;/extras/google/google_play_services/libproject/google-play-services_lib/</code> to the location where you maintain your Android app projects.</li>

  <li>In your app project, reference the Google Play services library project. See
    <a href="{@docRoot}tools/projects/projects-cmdline.html#ReferencingLibraryProject">Referencing
    a Library Project on the Command Line</a> for more information on how to do this.
    <p class="note"><strong>Note:</strong>
You should be referencing a copy of the library that you copied to your development
workspace&mdash;you should not reference the library directly from the Android SDK directory.</p>
  </li>
  <li>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
    <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application>}</a> element:
    <pre>
&lt;meta-data android:name="com.google.android.gms.version"
        android:value="&#64;integer/google_play_services_version" />
    </pre>
  </li>
</ol>

<p>Once you've set up your project to reference the library project,
you can begin developing features with the
<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>

</div><!-- end other -->


<h2 id="Proguard">Create a Proguard Exception</h2>

<p>To prevent <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> from stripping away
required classes, add the following lines in the
<code>&lt;project_directory&gt;/proguard-project.txt</code> file:
<pre>
-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 &#64;com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
    &#64;com.google.android.gms.common.annotation.KeepName *;
}

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

<p class="note"><strong>Note:</strong> When using Android Studio, you must add Proguard
to your <code>gradle.build</code> file's build types. For more information, see the
<a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Running-ProGuard"
>Gradle Plugin User Guide</a>.
</ol>


<h2 id="ensure">Ensure Devices Have the Google Play services APK</h2>

<p>As described in the <a href="{@docRoot}google/play-services/index.html">Google Play services
introduction</a>, 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.</p>

<p class="caution">
<strong>Important:</strong>
    Because it is hard to anticipate the state of each device, you must <em>always</em> 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
    {@link android.app.Activity#onResume onResume()} method of the main activity.
</p>

<p>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.</p>

<p>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.</p>

<p>To verify the Google Play services version, call <a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#isGooglePlayServicesAvailable(android.content.Context)"
>{@code isGooglePlayServicesAvailable()}</a>. If the result code is
<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SUCCESS"
>{@code SUCCESS}</a>,
        then the Google Play services APK is up-to-date and you can continue to make a connection.
If, however, the result code is
<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_MISSING"
>{@code SERVICE_MISSING}</a>,
<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_VERSION_UPDATE_REQUIRED"
>{@code SERVICE_VERSION_UPDATE_REQUIRED}</a>,
        or
<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_DISABLED"
>{@code SERVICE_DISABLED}</a>, then the user needs to install an update. So,
  call <a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)"
  >{@code GooglePlayServicesUtil.getErrorDialog()}</a> and pass it the result error code.
This returns a {@link android.app.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.</p>


<p>To then begin a connection to Google Play services (required by most Google APIs such
as Google Drive, Google+, and Games), read <a
href="{@docRoot}google/auth/api-client.html">Accessing Google APIs</a>.</p>