| page.title=Setup |
| @jd:body |
| |
| |
| <p> |
| The Google Play services SDK is an extension to the Android SDK and is available to you as a |
| downloadable package from the <a href="{@docRoot}tools/help/sdk-manager.html">SDK |
| Manager</a>. The download includes the client library and code samples. |
| </p> |
| |
| <p>You must download the Google Play services SDK in order to develop using the |
| <a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>. However, <strong>you |
| cannot use the Android emulator</strong> to test an app that depends on the Google Play services |
| APIs—you must use a real device running Android 2.2 or higher that includes |
| Google Play Store.</p> |
| |
| |
| <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> |
| Scroll to the bottom of the package list, select <b>Extras > Google Play services</b>, |
| and install it. |
| <p>The Google Play services SDK is saved in your Android SDK environment at |
| <code><android-sdk-folder>/extras/google/google_play_services/</code>.</p> |
| </li> |
| <li>Copy the <code><android-sdk-folder>/extras/google/google_play_services/libproject/google-play-services_lib</code> |
| library project into the source tree 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> |
| |
| |
| <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 |
| source tree—you should not reference the library 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(); |
| } |
| </pre> |
| </ol> |
| |
| <h2 id="ensure">Ensuring 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 in your app 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> |
| <span> |
| 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. |
| </span> |
| </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> |