| page.title=Set Up Google Play Services SDK |
| @jd:body |
| |
| |
| <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.2 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. |
| <ul> |
| <li>From 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.</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> |
| </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> |
| <p class="note"><strong>Note:</strong> Only Android 4.2.2 and higher versions of the |
| Google APIs platform include Google Play services.</p> |
| </li> |
| <li>Make a copy of the Google Play services library project. |
| <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 with the Library</h2> |
| |
| <p>To set up a project to use the Google Play services SDK:</p> |
| |
| <ol> |
| <li>Reference the library project in your Android project. |
| <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> |
| </li> |
| <li>If you are using <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>, add the following |
| lines in the <code><project_directory>/proguard-project.txt</code> file |
| to prevent ProGuard from stripping away required classes: |
| <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 * { |
| @ccom.google.android.gms.common.annotation.KeepName *; |
| } |
| |
| -keepnames class * implements android.os.Parcelable { |
| public static final ** CREATOR; |
| } |
| </pre> |
| </ol> |
| |
| <p>Once you have the Google Play services library project added to your app project, |
| you can begin developing features with the |
| <a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p> |
| |
| |
| |
| <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.2 through the Google Play Store app. However, updates might not reach |
| all users immediately.</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>Here are four scenarios that describe the possible state of the Google Play services APK on |
| a user's device:</p> |
| <ol> |
| <li> |
| A recent version of the Google Play Store app is installed, and the most recent Google Play |
| services APK has been downloaded. |
| </li> |
| <li> |
| A recent version of the Google Play Store app is installed, but the most recent Google Play |
| services APK has <em>not</em> been downloaded. |
| </li> |
| <li> |
| An old version of the Google Play Store app, which does not proactively download Google Play |
| services updates, is present. |
| </li> |
| <li> |
| The Google Play services APK is missing or disabled on the device, which might happen if the |
| user explicitly uninstalls or disables it. |
| </li> |
| </ol> |
| <p> |
| Case 1 is the success scenario and is the most common. However, because the other scenarios can |
| still happen, you must handle them every time your app connects to a Google Play service to |
| ensure that the Google Play services APK is present, up-to-date, and enabled. |
| </p> |
| <p> |
| To help you, the Google Play services client library has utility methods to |
| determine whether or not the Google Play services APK is recent enough to support the |
| version of the client library you are using. If not, the client library sends users to the |
| Google Play Store to download the recent version of the Google Play services APK. |
| </p> |
| |
| <p class="note"> |
| <b>Note:</b> |
| The Google Play services APK is not visible by searching the Google Play Store. The client |
| library provides a deep link into the Google Play Store when it detects that the device has a |
| missing or incompatible Google Play services APK. |
| </p> |
| |
| <p> |
| It is up to you choose the appropriate place in your app to do the following steps to check for |
| a valid Google Play services APK. For example, if Google Play services is required for your app, |
| 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 do these checks if the user navigates to that portion |
| of your app: |
| </p> |
| |
| <ol> |
| <li> |
| Query for the status of Google Play services on the device with the |
| <a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#isGooglePlayServicesAvailable(android.content.Context)" |
| >{@code isGooglePlayServicesAvailable()}</a> method, which returns a result code. |
| </li> |
| <li> |
| 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 proceed as normal. |
| </li> |
| <li> |
| If 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 |
| call <a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)" |
| >{@code getErrorDialog()}</a> |
| to display an error message to the user, which allows the user to download the APK |
| from the Google Play Store or enable it in the device's system settings. |
| </li> |
| </ol> |
