diff options
Diffstat (limited to 'docs/html/google/gcm/client.jd')
| -rw-r--r-- | docs/html/google/gcm/client.jd | 146 |
1 files changed, 77 insertions, 69 deletions
diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd index d44ee3c..9cb3f84 100644 --- a/docs/html/google/gcm/client.jd +++ b/docs/html/google/gcm/client.jd @@ -1,4 +1,4 @@ -page.title=Implementing GCM Client +page.title=Implementing GCM Client on Android page.tags=cloud,push,messaging @jd:body @@ -15,8 +15,8 @@ page.tags=cloud,push,messaging <ol class="toc"> <li><a href="#sample-play">Check for Google Play Services APK</a></li> <li><a href="#sample-register">Register for GCM</a></li> - <li><a href="#sample-send">Send a message</a></li> - <li><a href="#sample-receive">Receive a message</a></li> + <li><a href="#sample-receive">Receive a downstream message</a></li> + <li><a href="#sample-send">Send an upstream message</a></li> </ol> <li><a href="#run">Running the Sample</a></li> <li><a href="#stats">Viewing Statistics</a></li> @@ -34,14 +34,26 @@ page.tags=cloud,push,messaging </div> </div> -<p>A Google Cloud Messaging (GCM) client is a GCM-enabled app that runs on an +<p>A Google Cloud Messaging (GCM) Android client is a GCM-enabled app that runs on an Android device. To write your client code, we recommend that you use the <a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> -GCM APIs</a>. -The client helper library that was offered in previous versions of GCM still works, -but it has been superseded by the more efficient -<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> -GCM APIs</a>.</p> +{@code GoogleCloudMessaging}</a> API.</p> + +<p>Here are the requirements for running a GCM Android client:</p> + +<ul> + <li>At a bare minimum, GCM requires devices running Android 2.2 or higher that also have the +Google Play Store application installed, or an emulator running Android 2.2 +with Google APIs. Note that you are not limited to deploying your +Android applications through Google Play Store.</li> + <li>However, if you want to continue to use new GCM features that are distributed +through Google Play Services, the device must be running Android 2.3 or higher, or +you can use an emulator running Android 2.3 with Google APIs.</li> +<li>On Android devices, GCM uses an existing connection for Google services. For +pre-3.0 devices, this requires users to set up their Google accounts on their mobile +devices. A Google account is not a requirement on devices running Android 4.0.4 or higher.</li> + +</ul> <p>A full GCM implementation requires both a client implementation and a server implementation. For more @@ -58,7 +70,7 @@ registration ID), and a broadcast receiver to receive messages sent by GCM. <p>To write your client application, use the <a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> -GCM APIs</a>. +{@code GoogleCloudMessaging}</a> API. To use this API, you must set up your project to use the Google Play services SDK, as described in <a href="/google/play-services/setup.html">Setup Google Play Services SDK</a>.</p> @@ -88,9 +100,6 @@ If you're using Android Studio, this is the string to add to the the Android application can register and receive messages.</li> <li>The <code>android.permission.INTERNET</code> permission so the Android application can send the registration ID to the 3rd party server.</li> - <li>The <code>android.permission.GET_ACCOUNTS</code> permission as GCM requires -a Google account (necessary only if if the device is running a version lower than -Android 4.0.4)</li> <li>The <code>android.permission.WAKE_LOCK</code> permission so the application can keep the processor from sleeping when a message is received. Optional—use only if the app wants to keep the device from sleeping.</li> @@ -101,7 +110,7 @@ pattern—otherwise the Android application will not receive the messages.</ <li>A receiver for <code>com.google.android.c2dm.intent.RECEIVE</code>, with the category set as <code>applicationPackage</code>. The receiver should require the -<code>com.google.android.c2dm.SEND</code> permission, so that only the GCM +<code>com.google.android.c2dm.permission.SEND</code> permission, so that only the GCM Framework can send a message to it. If your app uses an {@link android.app.IntentService} (not required, but a common pattern), this receiver should be an instance of {@link android.support.v4.content.WakefulBroadcastReceiver}. @@ -324,8 +333,8 @@ private String getRegistrationId(Context context) { return ""; } // Check if app was updated; if so, it must clear the registration ID - // since the existing regID is not guaranteed to work with the new - // app version. + // since the existing registration ID is not guaranteed to work with + // the new app version. int registeredVersion = prefs.getInt(PROPERTY_APP_VERSION, Integer.MIN_VALUE); int currentVersion = getAppVersion(context); if (registeredVersion != currentVersion) { @@ -340,14 +349,14 @@ private String getRegistrationId(Context context) { */ private SharedPreferences getGCMPreferences(Context context) { // This sample app persists the registration ID in shared preferences, but - // how you store the regID in your app is up to you. + // how you store the registration ID in your app is up to you. return getSharedPreferences(DemoActivity.class.getSimpleName(), Context.MODE_PRIVATE); }</pre> <p>If the registration ID doesn't exist or the app was updated, {@code getRegistrationId()} returns an empty string -to indicate that the app needs to get a new regID. {@code getRegistrationId()} calls +to indicate that the app needs to get a new registration ID. {@code getRegistrationId()} calls the following method to check the app version:</p> <pre>/** @@ -400,7 +409,7 @@ private void registerInBackground() { // will send upstream messages to a server that echo back the // message using the 'from' address in the message. - // Persist the regID - no need to register again. + // Persist the registration ID - no need to register again. storeRegistrationId(context, regid); } catch (IOException ex) { msg = "Error :" + ex.getMessage(); @@ -433,7 +442,8 @@ private void sendRegistrationIdToBackend() { <p>After registering, the app calls {@code storeRegistrationId()} to store the registration ID in shared preferences for future use. This is just one way of -persisting a regID. You might choose to use a different approach in your app:</p> +persisting a registration ID. You might choose to use a different approach in +your app:</p> <pre>/** * Stores the registration ID and app versionCode in the application's @@ -455,64 +465,22 @@ private void storeRegistrationId(Context context, String regId) { <h4 id="reg-errors">Handle registration errors</h4> <p>As stated above, an Android app must register with GCM servers and get a registration ID -(regID) before it can receive messages. A given regID is not guaranteed to last indefinitely, -so the first thing your app should always do is check to make sure it has a valid regID -(as shown in the code snippets above).</p> +before it can receive messages. A given registration ID is not guaranteed to last indefinitely, +so the first thing your app should always do is check to make sure it has a valid +registration ID (as shown in the code snippets above).</p> -<p>In addition to confirming that it has a valid regID, your app should be prepared to handle +<p>In addition to confirming that it has a valid registration ID, your app should be prepared to handle the registration error {@code TOO_MANY_REGISTRATIONS}. This error indicates that the device has too many apps registered with GCM. The error only occurs in cases where there are extreme numbers of apps, so it should not affect the average user. The remedy is to prompt -the user to delete some of the other GCM-enabled apps from the device to make +the user to delete some of the other client apps from the device to make room for the new one.</p> - -<h3 id="sample-send">Send a message</h3> -<p>When the user clicks the app's <strong>Send</strong> button, the app sends an -upstream message using the -<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> API. In order to receive the upstream message, -your server should be connected to CCS. You can use one of the demo servers in -<a href="ccs.html#implement">Implementing an XMPP-based App Server</a> to run the sample and connect -to CCS.</p> - -<pre>public void onClick(final View view) { - if (view == findViewById(R.id.send)) { - new AsyncTask<Void, Void, String>() { - @Override - protected String doInBackground(Void... params) { - String msg = ""; - try { - Bundle data = new Bundle(); - data.putString("my_message", "Hello World"); - data.putString("my_action", - "com.google.android.gcm.demo.app.ECHO_NOW"); - String id = Integer.toString(msgId.incrementAndGet()); - gcm.send(SENDER_ID + "@gcm.googleapis.com", id, data); - msg = "Sent message"; - } catch (IOException ex) { - msg = "Error :" + ex.getMessage(); - } - return msg; - } - - @Override - protected void onPostExecute(String msg) { - mDisplay.append(msg + "\n"); - } - }.execute(null, null, null); - } else if (view == findViewById(R.id.clear)) { - mDisplay.setText(""); - } -}</pre> - -<h3 id="sample-receive">Receive a message</h3> +<h3 id="sample-receive">Receive a downstream message</h3> <p>As described above in <a href="#manifest">Step 2</a>, the app includes a {@link android.support.v4.content.WakefulBroadcastReceiver} for the <code>com.google.android.c2dm.intent.RECEIVE</code> -intent. A broadcast receiver is the mechanism GCM uses to deliver messages. When {@code onClick()} -calls {@code gcm.send()}, it triggers the broadcast receiver's {@code onReceive()} -method, which has the responsibility of making sure that the GCM message gets handled.</p> +intent. A broadcast receiver is the mechanism GCM uses to deliver messages. </p> <p>A {@link android.support.v4.content.WakefulBroadcastReceiver} is a special type of broadcast receiver that takes care of creating and managing a @@ -646,6 +614,46 @@ public class GcmIntentService extends IntentService { } }</pre> + +<h3 id="sample-send">Send an upstream message</h3> +<p>When the user clicks the app's <strong>Send</strong> button, the app sends an +upstream message using the +<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> +{@code GoogleCloudMessaging}</a> API. In order to receive the upstream message, +your server should be connected to CCS. You can use one of the demo servers in +<a href="ccs.html#implement">Implementing an XMPP-based App Server</a> to run the sample and connect +to CCS.</p> + +<pre>public void onClick(final View view) { + if (view == findViewById(R.id.send)) { + new AsyncTask<Void, Void, String>() { + @Override + protected String doInBackground(Void... params) { + String msg = ""; + try { + Bundle data = new Bundle(); + data.putString("my_message", "Hello World"); + data.putString("my_action", + "com.google.android.gcm.demo.app.ECHO_NOW"); + String id = Integer.toString(msgId.incrementAndGet()); + gcm.send(SENDER_ID + "@gcm.googleapis.com", id, data); + msg = "Sent message"; + } catch (IOException ex) { + msg = "Error :" + ex.getMessage(); + } + return msg; + } + + @Override + protected void onPostExecute(String msg) { + mDisplay.append(msg + "\n"); + } + }.execute(null, null, null); + } else if (view == findViewById(R.id.clear)) { + mDisplay.setText(""); + } +}</pre> + <h2 id="run">Running the Sample</h2> <p>To run the sample:</p> |