| page.title=Set Up Google Play Services SDK |
| @jd:body |
| |
| |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#Install">Install the Google Play Services SDK</a></li> |
| <li><a href="#Setup">Set Up a Project that Uses Google Play Services</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> |
| |
| |
| |
| <p>To develop an app using the <a href="{@docRoot}reference/gms-packages.html">Google |
| Play services APIs</a>, you must download the Google Play services SDK |
| from the <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>. |
| The download includes the client library and code samples.</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> |
| |
| <p>Ideally, you should develop and test your app on a variety of devices, including |
| both phones and tablets.</p> |
| |
| |
| <h2 id="Install">Install the Google Play Services SDK</h2> |
| |
| <p>To install the Google Play services SDK for development:</p> |
| |
| <ol> |
| <li>Launch the SDK Manager in one of the following ways: |
| <ul> |
| <li>In Android Studio, click <strong>SDK Manager</strong> |
| <img src="{@docRoot}images/tools/sdk-manager-studio.png" style="vertical-align:bottom;margin:0;height:19px" /> |
| in the toolbar.</li> |
| <li>In Eclipse (with <a href="{@docRoot}tools/help/adt.html">ADT</a>), |
| select <strong>Window</strong> > <strong>Android SDK Manager</strong>.</li> |
| <li>On Windows, double-click the <code>SDK Manager.exe</code> file at the root of the Android |
| SDK directory.</li> |
| <li>On Mac or Linux, open a terminal and navigate to the <code>tools/</code> directory in the |
| Android SDK, then execute <code>android sdk</code>.</li> |
| </ul> |
| </li> |
| <li>Install the Google Play services SDK. |
| <p>Scroll to the bottom of the package list, expand <b>Extras</b>, select |
| <b>Google Play services</b>, and install it. If you're using Android Studio, also install |
| <b>Google Repository</b> (it provides the Maven repository used for Gradle builds).</p> |
| <p>The Google Play services SDK is saved in your Android SDK environment at |
| <code><android-sdk>/extras/google/google_play_services/</code>.</p> |
| |
| <p class="note"><strong>Note:</strong> 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 |
| <b>Google Play services for Froyo</b> from the SDK Manager.</p> |
| |
| </li> |
| <li>Install a compatible version of the Google APIs platform. |
| <p>If you want to test your app on the emulator, expand the directory for <b>Android 4.2.2 |
| (API 17)</b> or a higher version, select <b>Google APIs</b>, and install it. Then create a |
| new <a href="{@docRoot}tools/devices/index.html">AVD</a> with Google APIs as |
| the platform target.</p> |
| </li> |
| <li>Make a copy of the Google Play services library project. |
| <p class="note"><strong>Note:</strong> If you are using Android Studio, skip this step.</p> |
| <p>Copy the library project at |
| <code><android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/</code> |
| to the location where you maintain your Android app projects. |
| <p>If you are using Eclipse, import the library project into your 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.</p> |
| </li> |
| </ol> |
| |
| |
| |
| <h2 id="Setup">Set Up a Project that Uses Google Play Services</h2> |
| |
| <p><b>Using Android Studio:</b></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:+' |
| <strong>compile 'com.google.android.gms:play-services:4.4.52'</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 <application>}</a> |
| element: |
| <pre> |
| <meta-data android:name="com.google.android.gms.version" |
| android:value="@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> |
| |
| |
| <p><b>Using Eclipse or another IDE:</b></p> |
| |
| <p>To make the Google Play services APIs available to your app, you must reference the library |
| project you created in step 4 of the <a href="#Install">installation instructions</a>.</p> |
| <p>See the <a href="{@docRoot}tools/projects/projects-eclipse.html#ReferencingLibraryProject" |
| >Referencing a Library Project for Eclipse</a> or <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> |
| |
| <p class="note"><strong>Note:</strong> |
| 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.</p> |
| |
| <p>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 <application>}</a> |
| element: |
| <pre> |
| <meta-data android:name="com.google.android.gms.version" |
| android:value="@integer/google_play_services_version" /> |
| </pre> |
| |
| |
| <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> |
| |
| |
| |
| <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><project_directory>/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 @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; |
| } |
| </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, read <a |
| href="{@docRoot}google/auth/api-client.html">Accessing Google Play Services APIs</a>.</p> |