diff options
Diffstat (limited to 'docs/html/google/gcm/gcm.jd')
| -rw-r--r-- | docs/html/google/gcm/gcm.jd | 146 |
1 files changed, 96 insertions, 50 deletions
diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index ce28fb8..7486d7b 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -1,4 +1,4 @@ -page.title=GCM Architectural Overview +page.title=Google Cloud Messaging for Android @jd:body <div id="qv-wrapper"> @@ -20,6 +20,11 @@ page.title=GCM Architectural Overview <li><a href="#arch">Architectural Overview</a> <ol> <li><a href="#lifecycle">Lifecycle Flow</a></li> + <ol> + <li><a href="#register">Enable GCM</a></li> + <li><a href="#push-process">Send a message</a></li> + <li><a href="#receiving">Receive a message</a></li> + </ol> <li><a href="#user">What Does the User See?</a></li> </ol> </li> @@ -27,8 +32,8 @@ page.title=GCM Architectural Overview <ol> <li><a href="#manifest">Creating the Manifest</a></li> <li><a href="#registering">Registering for GCM</a></li> - <li><a href="#unregistering">Unregistering from GCM</a></li> - <li><a href="#handling_intents">Handling Intents sent by GCM</a> + + <li><a href="#handling_intents">Handling Intents Sent by GCM</a> <ol> <li><a href="#handling_reg">Handling Registration Results</a></li> <li><a href="#received_data">Handling Received Data</a></li> @@ -46,7 +51,7 @@ page.title=GCM Architectural Overview </ol> </li> </ol> - <li><a href="#stats">Viewing statistics</a> + <li><a href="#stats">Viewing Statistics</a> </li> <li><a href="#example">Examples</a></li> </ol> @@ -58,20 +63,25 @@ page.title=GCM Architectural Overview <p>Google Cloud Messaging for Android (GCM) is a free service that helps developers send data from servers to their Android applications on Android -devices. This could be a lightweight message telling the Android application +devices, and upstream messages from the user's device back to the cloud. +This could be a lightweight message telling the Android application that there is new data to be fetched from the server (for instance, a movie uploaded by a friend), or it could be a message containing up to 4kb of payload data (so apps like instant messaging can consume the message directly). The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device.</p> + +<p>GCM introduces GCM Cloud Connection Server (CCS), which you can use +in tandem with GCM HTTP service/endpoint/APIs. +CCS uses XMPP, and it offers asynchronous, bidirectional +messaging. For more information, see +<a href="ccs.html">GCM Cloud Connection Server</a>. <p class="note"> To jump right into using GCM with your Android applications, see the instructions in <a href="gs.html">Getting Started</a>.</p> - - <h2 id="intro">Introduction</h2> <p>Here are the primary characteristics of Google Cloud @@ -80,6 +90,7 @@ Messaging (GCM):</p> <ul> <li>It allows 3rd-party application servers to send messages to their Android applications.</li> + <li>Using the <a href="ccs.html">GCM Cloud Connection Server</a>, you can receive upstream messages from the user's device.</li> <li>An Android application on an Android device doesn't need to be running to receive messages. The system will wake up the Android application via Intent broadcast when the message arrives, as long as the application is set up with the proper broadcast receiver and permissions.</li> @@ -170,24 +181,35 @@ which would cause delivery errors. server that gives the application server authorized access to Google services. The API key is included in the header of POST requests that send messages.</td> </tr> + + <tr> + <td><strong>Notification Key</strong></td> + <td>Part of the user notifications feature, which provides a mapping between a user and instances of an app running on multiple devices owned by the user. The {@code notification_key} is the token that GCM uses to fan out notifications to all devices whose registration IDs are associated with the key. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>.</td> + </tr> + +<tr> + <td><strong>Notification Key Name</strong></td> + <td>Part of the user notifications feature. The {@code notification_key_name} is a name or identifier (can be a username for a 3rd-party app) that is unique to a given user. It is used by third parties to group together registration IDs for a single user. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>.</td> + </tr> + </table> <h3 id="lifecycle">Lifecycle Flow</h3> -<p>Here are the primary processes involved in cloud-to-device messaging:</p> - <ul> - <li><a href="#register">Enabling GCM</a>. An Android application running on a + <li><a href="#register">Enable GCM</a>. An Android application running on a mobile device registers to receive messages.</li> - <li><a href="#push-process">Sending a message</a>. A 3rd-party application + <li><a href="notifications.html">User Notifications</a>. A 3rd-party server can optionally group multiple registration IDs +in a {@code notification_key} to send messages to multiple devices owned by a single user.</li> + <li><a href="#push-process">Send a message</a>. A 3rd-party application server sends messages to the device.</li> - <li><a href="#receiving">Receiving a message</a>. An Android application + <li><a href="#receiving">Receive a message</a>. An Android application receives a message from a GCM server.</li> </ul> <p>These processes are described in more detail below.</p> -<h4 id="register">Enabling GCM</h4> +<h4 id="register">Enable GCM</h4> <p>This is the sequence of events that occurs when an Android application running on a mobile device registers to receive messages:<span @@ -195,7 +217,7 @@ class="red-text"></span></p> <ol> <li>The first time the Android application needs to use the messaging service, it -fires off a registration Intent to a GCM server. +fires off a registration Intent to a GCM server. <p>This registration Intent (<code>com.google.android.c2dm.intent.REGISTER</code>) includes the sender ID, and the Android application ID.</p> <p class="note"><strong>Note:</strong> Because there is no lifecycle method that is called when the application is run for @@ -204,7 +226,7 @@ the first time, the registration intent should be sent on <code>onCreate()</code </li> <li>If the registration is successful, the GCM server broadcasts a <code>com.google.android.c2dm.intent.REGISTRATION</code> intent which gives the Android application a registration ID. - <p>The Android application should store this ID for later use (for instance, to check on <code>onCreate()</code> if it is already registered). + <p>The Android application should store this ID for later use (for instance, to check on <code>onCreate()</code> if it is already registered). Note that Google may periodically refresh the registration ID, so you should design your Android application with the understanding that the <code>com.google.android.c2dm.intent.REGISTRATION</code> intent may be called multiple times. Your Android application needs to be able to respond @@ -217,22 +239,26 @@ ID in a database. </li> <p>The registration ID lasts until the Android application explicitly unregisters itself, or until Google refreshes the registration ID for your Android application.</p> -<p class="note"><strong>Note:</strong> When users uninstall an application, it is not automatically unregistered on GCM. It is only unregistered when the GCM server tries to send a message to the device and the device answers that the application is uninstalled or it does not have a broadcast receiver configured to receive <code>com.google.android.c2dm.intent.RECEIVE</code> intents. At that point, your server should mark the device as unregistered (the server will receive a <code><a href="#unreg_device">NotRegistered</a></code> error). +<p class="note"><strong>Note:</strong> When users uninstall an application, it is not automatically unregistered on GCM. It is only unregistered when the GCM server tries to send a message to the device and the device answers that the application is uninstalled or it does not have a broadcast receiver configured to receive <code>com.google.android.c2dm.intent.RECEIVE</code> intents. At that point, your server should mark the device as unregistered (the server will receive a <code><a href="#unreg_device">NotRegistered</a></code> error).</p> <p> -Note that it might take a few minutes for the registration ID to be completely removed from the GCM server. So if the 3rd party server sends a message during this time, it will get a valid message ID, even though the message will not be delivered to the device.</p> -</p> +Note that it might take a few minutes for the registration ID to be completely removed from the GCM server. So if the 3rd-party server sends a message during this time, it will get a valid message ID, even though the message will not be delivered to the device.</p> + + -<h4 id="push-process">Sending a Message</h4> + +<h4 id="push-process">Send a Message</h4> <p>For an application server to send a message to an Android application, the following things must be in place:</p> <ul> - <li>The Android application has a registration ID that allows it to receive messages + <li>The Android application has stored a target that it can specify as the recipient of a message. This can be one of the following: + <ul> + <li>A single registration ID (or an array of registration IDs) that allows the app to receive messages for a particular device.</li> - <li>The 3rd-party application server has stored the registration ID.</li> - - + <li>A {@code notification_key} and corresponding {@code notification_key_name}, used to map a single user to multiple registration IDs. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>.</li> + </ul> + </li> <li>An API key. This is something that the developer must have already set up on the application server for the Android application (for more discussion, see @@ -259,7 +285,7 @@ non-trivial processing, you may want to grab a {@link android.os.PowerManager.Wa <p> An Android application can unregister GCM if it no longer wants to receive messages.</p> -<h4 id="receiving">Receiving a Message</h4> +<h4 id="receiving">Receive a Message</h4> <p>This is the sequence of events that occurs when an Android application installed on a mobile device receives a message:</p> @@ -313,25 +339,21 @@ simpler approach), see <a href="gs.html">GCM: Getting Started</a>. <h3 id="manifest">Creating the Manifest</h3> -<p>Every Android application must have an <code>AndroidManifest.xml</code> file (with -precisely that name) in its root directory. The manifest presents essential -information about the Android application to the Android system, information the -system must have before it can run any of the Android application's code (for more -discussion of the manifest file, see the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android Developers Guide</a>. To use the GCM feature, the -manifest must include the following:</p> +<p>To use the GCM feature, the +<code>AndroidManifest.xml</code> file must include the following:</p> <ul> <li>The <code>com.google.android.c2dm.permission.RECEIVE</code> permission so 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.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.</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> <li>An <code>applicationPackage + ".permission.C2D_MESSAGE</code> permission to prevent other Android applications from registering and receiving the Android application's messages. The permission name must exactly match this pattern—otherwise the Android application will not receive the messages.</li> - <li>A receiver for <code>com.google.android.c2dm.intent.RECEIVE</code> and <code>com.google.android.c2dm.intent.REGISTRATION</code>, with the category set + <li>A receiver for <code>com.google.android.c2dm.intent.RECEIVE</code> and <code>com.google.android.c2dm.intent.REGISTRATION</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 Framework can send a message to it. Note that both registration and the receiving of messages are implemented as <a href="{@docRoot}guide/components/intents-filters.html">Intents</a>.</li> - <li>An intent service to handle the intents received by the broadcast receiver.</li> + <li>An intent service to handle the intents received by the broadcast receiver. Optional.</li> <li>If the GCM feature is critical to the Android application's function, be sure to set <code>android:minSdkVersion="8"</code> in the manifest. This ensures that the Android application cannot be installed in an environment in which it @@ -368,8 +390,19 @@ could not run properly. </li> </manifest> </pre> + <h3 id="registering">Registering for GCM</h3> +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h2>Streamlined Registration</h2> + <p>There is now a simpler alternative to registering and unregistering. Simply call the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">{@code GoogleCloudMessaging}</a> method +<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html#register">{@code register(senderID...)}</a>. +This method registers the application for GCM and returns the registration ID. To unregister, call the +<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html#unregister">{@code unregister()}</a> method (though you should rarely if ever need to unregister).</p> +</div> +</div> + <p>An Android application needs to register with GCM servers before it can receive messages. To register, the application sends an Intent (<code>com.google.android.c2dm.intent.REGISTER</code>), with 2 extra parameters: </p> @@ -383,7 +416,7 @@ allow the registration service to extract Android application information. </li> <p>For example:</p> -<pre class="prettyprint pretty-java">Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER"); +<pre style="clear:right">Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER"); // sets the app name in the intent registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0)); registrationIntent.putExtra("sender", senderID); @@ -415,10 +448,10 @@ startService(unregIntent); defines a broadcast receiver for the <code>com.google.android.c2dm.intent.REGISTRATION</code> and <code>com.google.android.c2dm.intent.RECEIVE</code> intents. These <a href="{@docRoot}guide/components/intents-filters.html">intents</a> are sent by GCM to indicate that a device was registered (or unregistered), or to deliver messages, respectively.</p> -<p>Handling these intents might require I/O operations (such as network calls to the 3rd party server), and +<p>Handling these intents might require I/O operations (such as network calls to the 3rd-party server), and such operations should not be done in the receiver's <code>onReceive()</code> method. -You may be tempted to spawn a new thread directly, but there are no guarantees that the process will run long enough for the thread to finish the work. -Thus the recommended way to handle the intents is to delegate them to a service, such as an {@link android.app.IntentService}. +You may be tempted to spawn a new thread directly, but there are no guarantees that the process will run long enough for the thread to finish the work. +Thus the recommended way to handle the intents is to delegate them to a service, such as an {@link android.app.IntentService}. For example:</p> @@ -476,18 +509,18 @@ public class MyIntentService extends IntentService { <p>When a <code>com.google.android.c2dm.intent.REGISTRATION</code> intent is received, it could potentially contain 3 extras: <code>registration_id</code>, <code>error</code>, and <code>unregistered</code>. -<p>When a registration succeeds, <code>registration_id</code> contains the registration ID and the other extras are not set. -The application must ensure that the 3rd-party server receives the registration ID. It may do so by saving the registration ID and sending it to the server. +<p>When a registration succeeds, <code>registration_id</code> contains the registration ID and the other extras are not set. +The application must ensure that the 3rd-party server receives the registration ID. It may do so by saving the registration ID and sending it to the server. If the network is down or there are errors, the application should retry sending the registration ID when the network is up again or the next time it starts.</p> <p class="note"><strong>Note:</strong> Although the <code>com.google.android.c2dm.intent.REGISTRATION</code> intent is typically received after a request was made by the application, Google may periodically refresh the registration ID. So the application must be prepared to handle it at any time.</p> -<p>When an unregistration succeeds, only the <code>unregistered</code> extra is set, and similar to the registration workflow, -the application must contact the 3rd-party server to remove the registration ID (note that the registration ID is not available in the intent, +<p>When an unregistration succeeds, only the <code>unregistered</code> extra is set, and similar to the registration workflow, +the application must contact the 3rd-party server to remove the registration ID (note that the registration ID is not available in the intent, but the application should have saved the registration ID when it got it).<p> -<p>If the application request (be it register or unregister) fails, the <code>error</code> will be set with an error code, and the other extras will not be set. +<p>If the application request (be it register or unregister) fails, the <code>error</code> will be set with an error code, and the other extras will not be set. Here are the possible error codes:</p> @@ -536,7 +569,7 @@ phone doesn't currently support GCM.</td> private void handleRegistration(Intent intent) { String registrationId = intent.getStringExtra("registration_id"); String error = intent.getStringExtra("error"); - String unregistered = intent.getStringExtra("unregistered"); + String unregistered = intent.getStringExtra("unregistered"); // registration succeeded if (registrationId != null) { // store registration ID on shared preferences @@ -561,12 +594,14 @@ private void handleRegistration(Intent intent) { } }</pre> + + <h4 id="received_data">Handling Received Data</h4> -<p>The <code>com.google.android.c2dm.intent.RECEIVE</code> intent is used by GCM to +<p>The <code>com.google.android.c2dm.intent.RECEIVE</code> intent is used by GCM to deliver the messages sent by the 3rd-party server to the application running in the device. -If the server included key-pair values in the <code>data</code> parameter, they are available as -extras in this intent, with the keys being the extra names. GCM also includes an extra called +If the server included key-pair values in the <code>data</code> parameter, they are available as +extras in this intent, with the keys being the extra names. GCM also includes an extra called <code>from</code> which contains the sender ID as an string, and another called <code>collapse_key</code> containing the collapse key (when in use). <p>Here is an example, again using the <code>MyIntentReceiver</code> class:</p> @@ -620,6 +655,7 @@ messages.</li> <p>This section describes how the 3rd-party application server sends messages to one or more mobile devices. Note the following:</p> <ul> <li>A 3rd-party application server can either send messages to a single device or to multiple devices. A message sent to multiple devices simultaneously is called a <em>multicast message</em>.</li> + <li>To send a single message to multiple devices owned by a single user, you can use a {@code notification_key}, as described in <a href="notifications.html">User Notifications</a>. <li>You have 2 choices in how you construct requests and responses: plain text or JSON.</li> <li>However, to send multicast messages, you must use JSON. Plain text will not work.</li> @@ -660,8 +696,19 @@ Authorization:key=AIzaSyB-1uEai2WiUapxCs2Q0GZYzPu7Udno5aA </tr> <tr> <td><code>registration_ids</code></td> - <td>A string array with the list of devices (registration IDs) receiving the message. It must contain at least 1 and at most 1000 registration IDs. To send a multicast message, you must use JSON. For sending a single message to a single device, you could use a JSON object with just 1 registration id, or plain text (see below). Required.</td> + <td>A string array with the list of devices (registration IDs) receiving the message. It must contain at least 1 and at most 1000 registration IDs. To send a multicast message, you must use JSON. For sending a single message to a single device, you could use a JSON object with just 1 registration id, or plain text (see below). A request must include a recipient—this can be either a registration ID, an array of registration IDs, or a {@code notification_key}.</td> + </tr> + <tr> + <td><code>notification_key</code></td> + <td>A string that maps a single user to multiple registration IDs associated with that user. This +allows a 3rd-party server to send a single message to multiple app instances (typically on multiple devices) owned by a single user. A 3rd-party server can use {@code notification_key} as the target for a message instead of an individual registration ID (or array of registration IDs). The maximum number of members allowed for a {@code notification_key} is 10. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>. Optional.</td> + </tr> + +<tr> + <td><code>notification_key_name</code></td> + <td>A name or identifier (can be a username for a 3rd-party app) that is unique to a given user. It is used by 3rd parties to group together registration IDs for a single user. The <code>notification_key_name</code> should be uniquely named per app in case you have multiple apps for the same project ID. This ensures that notifications only go to the intended target app. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>.</td> </tr> + <tr> <td><code>collapse_key</code></td> <td>An arbitrary string (such as "Updates Available") that is used to collapse a group of like messages @@ -1043,8 +1090,7 @@ A message was addressed to a registration ID whose package name did not match th registration_id=32 </pre> - -<h3 id="stats">Viewing statistics</h3> +<h3 id="stats">Viewing Statistics</h3> <p>To view statistics and any error messages for your GCM applications:</p> <ol> |