diff options
Diffstat (limited to 'docs/html/google/gcm/server.jd')
| -rw-r--r-- | docs/html/google/gcm/server.jd | 648 |
1 files changed, 332 insertions, 316 deletions
diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd index 20e2b2e..004fd0e 100644 --- a/docs/html/google/gcm/server.jd +++ b/docs/html/google/gcm/server.jd @@ -7,9 +7,9 @@ page.title=Implementing GCM Server <h2>In this document</h2> <ol class="toc"> - <li><a href="#choose">Choosing a GCM Connection Server</a></li> <li><a href="#role">Role of the 3rd-party Application Server</a></li> - <li><a href="#send-msg">Sending Messages</a> + <li><a href="#choose">Choosing a GCM Connection Server</a></li> + <li><a href="#send-msg">Sending Messages</a> <ol class="toc"> <li><a href="#target">Target</a></li> @@ -17,7 +17,18 @@ page.title=Implementing GCM Server <li><a href="#params">Message parameters</a> </ol> </li> - <li><a href="#receive">Receiving Messages</a> </li> + <li><a href="#adv">Messaging Concepts and Best Practices</a> + + <ol class="toc"> + + <li><a href="#collapsible">Send-to-Sync vs. Messages with Payload</a></li> + <li><a href="#ttl">Setting an Expiration Date for a Message</a></li> + <li><a href="#multi-senders">Receiving Messages from Multiple Senders</a> + <li><a href="#lifetime">Lifetime of a Message</a> + <li><a href="#throttling">Throttling</a> + </ol> + +</li> </li> </ol> @@ -25,6 +36,7 @@ page.title=Implementing GCM Server <h2>See Also</h2> <ol class="toc"> +<li><a href="server-ref.html">Server Reference</a></li> <li><a href="gs.html">Getting Started</a></li> <li><a href="client.html">Implementing GCM Client</a></li> <li><a href="ccs.html">Cloud Connection Server (XMPP)</a></li> @@ -37,388 +49,392 @@ page.title=Implementing GCM Server </div> -<p>The server side of Google Cloud Messaging (GCM) consists of 2 components:</p> +<p>The server side of Google Cloud Messaging (GCM) consists of two components:</p> <ul> <li>Google-provided <strong>GCM Connection Servers</strong> -take messages from a 3rd-party application server and send them to a GCM-enabled -Android application (the "client app") running on a device. For example, +take messages from a <a href="{@docRoot}google/gcm/server.html#role">3rd-party app server</a> +and send them to a GCM-enabled +application (the "client app") running on a device. For example, Google provides connection servers for <a href="{@docRoot}google/gcm/http.html"> -HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP).</li> +HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">XMPP (CCS)</a> (XMPP).</li> <li>A <strong>3rd-party application server</strong> that you must implement. This application -server sends data to a GCM-enabled Android application via the chosen GCM connection server.</li> +server sends data to a GCM-enabled client app via the chosen GCM connection server.</li> </ul> </p> +<p>A full GCM implementation requires both a client implementation and a server +implementation. For more +information about implementing the client side, see <a href="client.html"> +Implementing GCM Client</a>.</p> + + +<h2 id="role">Role of the 3rd-party Application Server</h2> + +<p>Before you can write client apps that use the GCM feature, you must +have an application server that meets the following criteria:</p> + +<ul> + <li>Able to communicate with your client.</li> + <li>Able to fire off properly formatted requests to the GCM server.</li> + <li>Able to handle requests and resend them as needed, using +<a href="http://en.wikipedia.org/wiki/Exponential_backoff">exponential back-off.</a></li> + <li>Able to store the API key and client registration IDs. In HTTP, the API key is +included in the header of POST requests that send messages. In XMPP, the API key is +used in the SASL PLAIN authentication request as a password to authenticate the connection.</li> + <li>Able to generate message IDs to uniquely identify each message it sends. Message IDs +should be unique per sender ID.</li> +</ul> + <p>Here are the basic steps you follow to implement your 3rd-party app server:</p> <ul> <li>Decide which GCM connection server(s) you want to use. Note that if you want to use - upstream messaging from your client applications, you must use CCS. For a more detailed + upstream messaging from your client applications, you must use XMPP (CCS). For a more detailed discussion of this, see <a href="#choose"> Choosing a GCM Connection Server</a>.</li> - <li>Decide how you want to implement your app server. For example: + <li>Decide how you want to implement your app server. We provide helper libraries and code +samples to assist you with your 3rd-party app server implementation. For example: <ul> <li>If you decide to use the HTTP connection server, you can use the GCM server helper library and demo app to help in implementing your app server.</li> <li>If you decide to use the XMPP connection server, you can use the provided Python or Java <a href="http://www.igniterealtime.org/projects/smack/"> Smack</a> demo apps as a starting point.</li> - <li>Note that Google AppEngine does not support connections to CCS.</li> + <li>Note that Google AppEngine does not support connections to XMPP (CCS).</li> </ul> </li> </ul> </li> </ul> -<p>A full GCM implementation requires both a client implementation and a server -implementation. For more -information about implementing the client side, see <a href="client.html"> -Implementing GCM Client</a>.</p> <h2 id="choose">Choosing a GCM Connection Server</h2> <p>Currently GCM provides two connection servers: <a href="{@docRoot}google/gcm/http.html"> -HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">CCS</a> (XMPP). You can use them -separately or in tandem. CCS messaging differs from GCM HTTP messaging in the following ways:</p> +HTTP</a> and <a href="{@docRoot}google/gcm/ccs.html">XMPP (CCS)</a>. You can use them +separately or in tandem. XMPP (CCS) messaging differs from HTTP messaging in the following ways:</p> <ul> <li>Upstream/Downstream messages <ul> - <li>GCM HTTP: Downstream only: cloud-to-device. </li> - <li>CCS: Upstream and downstream (device-to-cloud, cloud-to-device). </li> + <li>HTTP: Downstream only, cloud-to-device up to 4KB of data. </li> + <li>XMPP (CCS): Upstream and downstream (device-to-cloud, cloud-to-device), + up to 4 KB of data. </li> </ul> </li> - <li>Asynchronous messaging + <li>Messaging (synchronous or asynchronous) <ul> - <li>GCM HTTP: 3rd-party app servers send messages as HTTP POST requests and -wait for a response. This mechanism is synchronous and causes the sender to block -before sending another message.</li> - <li>CCS: 3rd-party app servers connect to Google infrastructure using a -persistent XMPP connection and send/receive messages to/from all their devices -at full line speed. CCS sends acknowledgment or failure notifications (in the + <li>HTTP: Synchronous. 3rd-party app servers send messages as HTTP POST requests and +wait for a response. This mechanism is synchronous and blocks the sender from sending +another message until the response is received.</li> + <li>XMPP (CCS): Asynchronous. 3rd-party app servers send/receive messages to/from all their +devices at full line speed over persistent XMPP connections. +XMPP (CCS) sends acknowledgment or failure notifications (in the form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.</li> </ul> </li> <li>JSON <ul> - <li>GCM HTTP: JSON messages sent as HTTP POST.</li> - <li>CCS: JSON messages encapsulated in XMPP messages.</li> + <li>HTTP: JSON messages sent as HTTP POST.</li> + <li>XMPP (CCS): JSON messages encapsulated in XMPP messages.</li> + </ul> + </li> + <li>Plain Text + <ul> + <li>HTTP: Plain Text messages sent as HTTP POST.</li> + <li>XMPP (CCS): Not supported.</li> + </ul> + </li> + <li>Multicast downstream send to multiple registration IDs. + <ul> + <li>HTTP: Supported in JSON message format.</li> + <li>XMPP (CCS): Not supported.</li> </ul> </li> </ul> -<h2 id="role">Role of the 3rd-party Application Server</h2> -<p>Before you can write client Android applications that use the GCM feature, you must -have an application server that meets the following criteria:</p> +<h2 id="send-msg">Sending Messages</h2> -<ul> - <li>Able to communicate with your client.</li> - <li>Able to fire off properly formatted requests to the GCM server.</li> - <li>Able to handle requests and resend them as needed, using -<a href="http://en.wikipedia.org/wiki/Exponential_backoff">exponential back-off.</a></li> - <li>Able to store the API key and client registration IDs. The -API key is included in the header of POST requests that send -messages.</li> - <li>Able to generate message IDs to uniquely identify each message it sends. Message IDs -should be unique per sender ID.</li> -</ul> +<p>This section gives an overview of sending messages. For details of message syntax, +see <a href="{@docRoot}google/gcm/server-ref.html">Server Reference</a>.</p> -<h2 id="send-msg">Sending Messages</h2> +<h3>Overview</h3> <p>Here is the general sequence of events that occurs when a 3rd-party application -server sends a message:</p> +server sends a message (the details vary depending on the platform):</p> <ol> - <li>The application server sends a message to GCM servers.</li> - <li>Google enqueues and stores the message in case the device is offline.</li> - <li>When the device is online, Google sends the message to the device.</li> - <li>On the device, the system broadcasts the message to the specified Android -application via Intent broadcast with proper permissions, so that only the targeted -Android application gets the message. This wakes the Android application up. -The Android application does not need to be running beforehand to receive the message.</li> - <li>The Android application processes the message. </li> + <li>The 3rd-party app server sends a message to GCM servers.</li> + <li>The GCM connection server enqueues and stores the message if the device is offline.</li> + <li>When the device is online, GCM connection server sends the message to the device.</li> + <li>The client app processes the message. </li> </ol> -<p>The following sections describe the basic requirements for -sending messages.</p> +<h3>Implement send request</h3> + +<p>The following sections describe the basic components involved in +sending a request. See the <a href="{@docRoot}google/gcm/server-ref.html">Server Reference</a> +for details.</p> -<h3 id="target">Target</h3> +<h4 id="target">Target</h4> <p>Required. When your app server sends a message in GCM, it must specify a target.</p> -<p>For HTTP you must specify the target as one of:</p> +<p>For HTTP you must specify the target as one of the following:</p> <ul> <li><code>registration_ids</code>: For sending to 1 or more devices (up to 1000). When you send a message to multiple registration IDs, that is called a multicast message.</li> <li><code>notification_key</code>: For sending to multiple devices owned by a single user.</li> </ul> -<p>For CCS (XMPP):</p> +<p>For CCS (XMPP) you must specify the target as:</p> <ul> -<li>You must specify the target as the "to" field, where the "to" +<li>{@code to}: This field may contain a single registration ID or a notification key. -CCS does not support multicast messaging.</li> +XMPP (CCS) does not support multicast messaging.</li> </ul> -<h3 id="payload">Payload</h3> -<p>Optional. If you are including a payload in the message, you use the <code>data</code> -parameter to include the payload. This applies for both HTTP and CCS.</p> - -<h3 id="params">Message parameters</h3> - -<p>The following table lists the parameters that a 3rd-party app server might -include in the JSON messages it sends to a connection server. See the "Where Supported" -column for information about which connection servers support that particular -parameter.</p> - -<p class="table-caption" id="table1"> - <strong>Table 1.</strong> Message Parameters JSON (CCS and HTTP).</p> - -<table> - <tr> - <th>Parameter</th> - <th>Description</th> -<th>Where Supported</th> -</tr> - <td><code>to</code></td> -<td>In CCS, this parameter is used in place of <code>registration_ids</code> to -specify the recipient of a message. Its value must be a registration ID. -The value is a string. Required.</td> -<td>CCS</td> -</tr> -<tr> -<td><code>message_id</code></td> -<td>In CCS, this parameter uniquely identifies a message in an XMPP connection. -The value is a string that uniquely identifies the associated message. Required.</td> -<td>CCS</td> -</tr> -<tr> -<td><code>message_type</code></td> -<td>In CCS, this parameter indicates a special status message, typically sent by the system. -However, your app server also uses this parameter to send an 'ack' or 'nack' -message back to the CCS connection server. For more discussion of this topic, see -<a href="ccs.html">Cloud Connection Server</a>. The value is a string. Optional.</td> -<td>CCS</td> -<tr> - <td><code>registration_ids</code></td> - <td>This parameter specifies a string array containing 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}. -Required.</td> -<td>HTTP</td> -</tr> - <tr> - <td><code>notification_key</code></td> - <td>This parameter specifies 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 20. For more discussion -of this topic, see <a href="notifications.html">User Notifications</a>. Optional. -</td> -<td style="width:100px">HTTP. This feature is supported in CCS, but you use it by -specifying a notification key in the "to" field.</td> -</tr> - <tr> - <td><code>collapse_key</code></td> - <td>This parameter specifies an arbitrary string (such as -"Updates Available") that is used -to collapse a group of like messages -when the device is offline, so that only the last message gets sent to the -client. This is intended to avoid sending too many messages to the phone when it -comes back online. Note that since there is no guarantee of the order in which -messages get sent, the "last" message may not actually be the last -message sent by the application server. Messages with collapse keys are also called -<a href="#s2s">send-to-sync messages</a>. -<br> -<strong>Note:</strong> GCM allows a maximum of 4 different collapse keys to be -used by the GCM server -at any given time. In other words, the GCM server can simultaneously store 4 -different send-to-sync messages per device, each with a different collapse key. -If you exceed -this number GCM will only keep 4 collapse keys, with no guarantees about which -ones they will be. See <a href="adv.html#collapsible">Advanced Topics</a> for more -discussion of this topic. Optional.</td> -<td>CCS, HTTP</td> -</tr> - <tr> - <td><code>data</code></td> - <td>This parameter specifies a JSON object whose fields represents the -key-value pairs of the message's -payload data. If present, the payload data will be -included in the Intent as application data, with the key being the extra's name. -For instance, <code>"data":{"score":"3x1"}</code> would result in an intent extra -named <code>score</code> whose value is the string <code>3x1</code>. -There is no limit on the number of key/value pairs, though there is a limit on -the total size of the message (4kb). The values could be any JSON object, but we -recommend using strings, since the values will be converted to strings in the GCM -server anyway. If you want to include objects or other non-string data types -(such as integers or booleans), you have to do the conversion to string yourself. -Also note that the key cannot be a reserved word (<code>from</code> or any word -starting with <code>google.</code>). Using words defined in this table as field -names (such as <code>collapse_key</code>) could yield unpredictable outcomes and -is not recommended. Optional.</td> -<td>CCS, HTTP</td> -</tr> - <tr> - <td><code>delay_while_idle</code></td> - <td>This parameter indicates that the message should not be sent immediately -if the device is idle. The server will wait for the device to become active, and -then only the last message for each <code>collapse_key</code> value will be -sent. The default value is <code>false</code>, and must be a JSON boolean. Optional.</td> -<td>CCS, HTTP</td> -</tr> - <tr> - <td><code>time_to_live</code></td> - <td>This parameter specifies how long (in seconds) the message should be kept on GCM -storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as -a JSON number).</td> -<td>CCS, HTTP</td> -</tr> -<tr> - <td><code>restricted_package_name</code></td> - <td>This parameter specifies a string containing the package -name of your application. When set, messages -are only sent to registration IDs that match the package name. Optional. - </td> -<td>HTTP</td> -</tr> -<tr> - <td><code>dry_run</code></td> - <td>This parameter allows developers to test a request without actually -sending a message. Optional. The default value is <code>false</code>, and must -be a JSON boolean. - </td> -<td>HTTP</td> -</tr> -<tr> - <td><code>delivery_receipt_requested</code></td> - <td>This parameter lets you request confirmation of message delivery. When -this parameter is set to <code>true</code>, CCS sends a -delivery receipt when a device confirms that it received a message sent by CCS. -The default value is <code>false</code>, and must be a JSON boolean. Optional.<br /> -This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> -delivery receipts</a>. -</td> - <td>CCS</td> -</tr> -<tr> - <td><code>message_status</code></td> - <td>This parameter specifies the status of the receipt message. -The parameter appears inside the -<code>"data"</code> field of a -delivery receipt message. Currently the only possible value -is <code>MESSAGE_SENT_TO_DEVICE</code>, which indicates that a device acknowledges -receiving a message sent by CCS.<br /> -This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> -delivery receipts</a>.</td> - <td>CCS</td> -</tr> -<tr> - <td><code>original_message_id</code></td> - <td>The value of this parameter is the ID of the original message that the server sent to -the device. This parameter appears inside the <code>"data"</code> field of a -delivery receipt message. <br /> -This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> -delivery receipts</a>.</td> - <td>CCS</td> -</tr> -<tr> - <td><code>device_registration_id</code></td> - <td>For the purpose of tracking the delivery receipt, this parameter lists -the registration ID of the device to which a given message was sent. This parameter -appears inside the <code>"data"</code> field of a -delivery receipt message. <br /> -This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> -delivery receipts</a>.</td> - <td>CCS</td> -</tr> - -</table> +<h4 id="options">Options</h4> + +<p>There are various options the 3rd-party app server can set when sending a downstream +message to a client app. See the <a href="{@docRoot}google/gcm/server-ref.html#table1"> +Server Reference</a> for details. Here are a few examples of possible options:</p> + +<ul> + <li>{@code collapse_key}: whether a message should be "send-to-sync" or a "message with +payload".</li> + <li>{@code time_to_live}: setting an expiration date for a message.</li> + <li>{@code dry_run}: Test your server. <p>If you want to test your request (either JSON or plain text) without delivering -the message to the devices, you can set an optional HTTP or JSON parameter called +the message to the devices, you can set an optional HTTP parameter called <code>dry_run</code> with the value <code>true</code>. The result will be almost identical to running the request without this parameter, except that the message will not be delivered to the devices. Consequently, the response will contain fake IDs for the message and multicast parameters.</p> +</li> +</ul> -<p>If you are using plain text instead of JSON, the message parameters must be set as -HTTP parameters sent in the body, and their syntax is slightly different, as -described in the following table: - -<p class="table-caption" id="table2"> - <strong>Table 2.</strong> Message Parameters Plain Text (HTTP only).</p> -<table> - <tr> - <th>Parameter</th> - <th>Description</th> - </tr> - <tr> - <td><code>registration_id</code></td> - <td>This parameter specifies the registration ID of the single device -receiving the message. -Required.</td> - </tr> - <tr> - <td><code>collapse_key</code></td> - <td>Same as JSON (see previous table). Optional.</td> - </tr> - <tr> - <td><code>data.<key></code></td> - - <td>This parameter specifies payload data, expressed as parameters -prefixed with <code>data.</code> and -suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would -result in an intent extra named <code>score</code> whose value is the string -<code>3x1</code>. There is no limit on the number of key/value parameters, though -there is a limit on the total size of the message. Also note that the key cannot -be a reserved word (<code>from</code> or any word starting with -<code>google.</code>). Using words defined in this table as field -names (such as <code>collapse_key</code>) could yield unpredictable outcomes and -is not recommended. Optional.</td> - - </tr> - <tr> - <td><code>delay_while_idle</code></td> - <td>This parameter specifies whether messages should be delivered when the device -is asleep. A value of <code>1</code> or <code>true</code> indicates -<code>true</code>, and anything else indicates <code>false</code>. Optional. The default -value is <code>false</code>.</td> - </tr> - <tr> - <td><code>time_to_live</code></td> - <td>Same as JSON (see previous table). Optional.</td> - </tr> -<tr> - <td><code>restricted_package_name</code></td> - <td>Same as JSON (see previous table). Optional. - </td> -</tr> -<tr> - <td><code>dry_run</code></td> - <td>Same as JSON (see previous table). Optional. - </td> -</tr> -</table> - -<h2 id="receive">Receiving Messages</h2> - -<p>This is the sequence of events that occurs when an Android application -installed on a mobile device receives a message:</p> +<h4 id="payload">Payload</h4> +<p>Optional. If you are including a payload in the message, you use the <code>data</code> +parameter to include the payload. This applies for both HTTP and XMPP.</p> + +<p>See the <a href="{@docRoot}google/gcm/server-ref.html">Server Reference</a> for details on sending +and receiving messages.</p> + +<h2 id="adv">Messaging Concepts and Best Practices</h2> + +<p>This section has a discussion of general messaging topics.</p> + +<h3 id="collapsible">Send-to-Sync vs. Messages with Payload</h3> + +<p>Every message sent in GCM has the following characteristics:</p> +<ul> + <li>It has a payload limit of 4096 bytes.</li> + <li>By default, it is stored by GCM for 4 weeks.</li> +</ul> + +<p>But despite these similarities, messages can behave very differently depending +on their particular settings. One major distinction between messages is whether +they are collapsed (where each new message replaces the preceding message) or not +collapsed (where each individual message is delivered). Every message sent in GCM +is either a "send-to-sync" (collapsible) message or a "message with +payload" (non-collapsible message).</p> + +<h4 id="s2s">Send-to-sync messages</h4> + +<p>A send-to-sync (collapsible) message is often a "tickle" that tells +a mobile application to sync data from the server. For example, suppose you have +an email application. When a user receives new email on the server, the server +pings the mobile application with a "New mail" message. This tells the +application to sync to the server to pick up the new email. The server might send +this message multiple times as new mail continues to accumulate, before the application +has had a chance to sync. But if the user has received 25 new emails, there's no +need to preserve every "New mail" message. One is sufficient. Another +example would be a sports application that updates users with the latest score. +Only the most recent message is relevant. </p> + +<p>GCM allows a maximum of 4 different collapse keys to be used by the GCM server +at any given time. In other words, the GCM server can simultaneously store 4 +different send-to-sync messages per device, each with a different collapse key. +For example, Device A can have A1, A2, A3, and A4. Device B can have B1, B2, B3, +and B4, and so on. If you exceed this number GCM will only keep 4 collapse keys, with no +guarantees about which ones they will be.</p> + +<h3 id="payload">Messages with payload</h3> + +<p>Unlike a send-to-sync message, every "message with payload" +(non-collapsible message) is delivered. The payload the message contains can be +up to 4kb. For example, here is a JSON-formatted message in an IM application in +which spectators are discussing a sporting event:</p> + +<pre class="prettyprint pretty-json">{ + "registration_id" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...", + "data" : { + "Nick" : "Mario", + "Text" : "great match!", + "Room" : "PortugalVSDenmark", + }, +}</pre> + +<p>A "message with payload" is not simply a "ping" to the +mobile application to contact the server to fetch data. In the aforementioned IM +application, for example, you would want to deliver every message, because every +message has different content. To specify a non-collapsible message, you simply +omit the <code>collapse_key</code> parameter. Thus GCM will send each message +individually. Note that the order of delivery is not guaranteed.</p> + +<p>GCM will store up to 100 non-collapsible messages. After that, all messages +are discarded from GCM, and a new message is created that tells the client how +far behind it is.</p> + +<p>The application should respond by syncing with the server to recover the +discarded messages. </p> + +<h4 id="which">Which should I use?</h4> + <p>If your application does not need to use non-collapsible messages, collapsible +messages are a better choice from a performance standpoint. However, if you use +collapsible messages, remember that <strong>GCM only allows a maximum of 4 different collapse +keys to be used by the GCM server per registration ID at any given time</strong>. You must +not exceed this number, or it could cause unpredictable consequences.</p> + +<h3 id="ttl">Setting an Expiration Date for a Message</h3> +<p>You can use the <code>time_to_live</code> parameter in the send request +to specify the maximum lifespan of a message. +The value of this parameter must be a duration from 0 to 2,419,200 seconds, and +it corresponds to the maximum period of time for which GCM will store and try to +deliver the message. Requests that don't contain this field default to the maximum +period of 4 weeks.</p> +<p>Here are some possible uses for this feature:</p> +<ul> + <li>Video chat incoming calls</li> + <li>Expiring invitation events</li> + <li>Calendar events</li> +</ul> +<h4 id="bg">Background </h4> +<p>GCM usually delivers messages immediately after they are sent. However, +this might not always be possible. For example, if the platform is Android, +the device could be turned off, offline, or otherwise unavailable. +Or the sender itself might request +that messages not be delivered until the device becomes active by using the +<code>delay_while_idle</code> flag. Finally, GCM might intentionally delay messages +to prevent an application from consuming excessive resources and negatively +impacting battery life.</p> + +<p>When this happens, GCM will store the message and deliver it as soon as it's +feasible. While this is fine in most cases, there are some applications for which +a late message might as well never be delivered. For example, if the message is +an incoming call or video chat notification, it will only be meaningful for a +small period of time before the call is terminated. Or if the message is an +invitation to an event, it will be useless if received after the event has ended.</p> + +<p>Another advantage of specifying the expiration date for a message is that GCM +will never throttle messages with a <code>time_to_live</code> value of 0 seconds. +In other words, GCM will guarantee best effort for messages that must be delivered +"now or never." Keep in mind that a <code>time_to_live</code> value of +0 means messages that can't be delivered immediately will be discarded. However, +because such messages are never stored, this provides the best latency for +sending notifications.</p> + +<p>Here is an example of a JSON-formatted request that includes TTL:</p> +<pre class="prettyprint pretty-json"> +{ + "collapse_key" : "demo", + "delay_while_idle" : true, + "registration_ids" : ["xyz"], + "data" : { + "key1" : "value1", + "key2" : "value2", + }, + "time_to_live" : 3 +}, +</pre> + + +<h3 id="multi-senders">Receiving Messages from Multiple Senders</h3> + +<p>GCM allows multiple parties to send messages to the same application. For +example, suppose your application is an articles aggregator with multiple +contributors, and you want each of them to be able to send a message when they +publish a new article. This message might contain a URL so that the application +can download the article. Instead of having to centralize all sending activity in +one location, GCM gives you the ability to let each of these contributors send +its own messages.</p> + +<p>To make this possible, all you need to do is have each sender generate its own +project number. Then include those IDs in the sender field, separated by commas, +when requesting a registration. Finally, share the registration ID with your +partners, and they'll be able to send messages to your application using their +own authentication keys.</p> + +<p>Note that there is limit of 100 multiple senders.</p> + +<h3 id="lifetime">Lifetime of a Message</h3> + +<p>When a 3rd-party server posts a message to GCM and receives a message ID back, +it does not mean that the message was already delivered to the device. Rather, it +means that it was accepted for delivery. What happens to the message after it is +accepted depends on many factors.</p> + +<p>In the best-case scenario, if the device is connected to GCM, the screen is on, +and there are no throttling restrictions (see <a href="#throttling">Throttling</a>), +the message will be delivered right away.</p> + +<p>If the device is connected but idle, the message will still be +delivered right away unless the <code>delay_while_idle</code> flag is set to true. +Otherwise, it will be stored in the GCM servers until the device is awake. And +that's where the <code>collapse_key</code> flag plays a role: if there is already +a message with the same collapse key (and registration ID) stored and waiting for +delivery, the old message will be discarded and the new message will take its place +(that is, the old message will be collapsed by the new one). However, if the collapse +key is not set, both the new and old messages are stored for future delivery. +Collapsible messages are also called <a href="#s2s">send-to-sync messages</a>.</p> + +<p class="note"><strong>Note:</strong> There is a limit on how many messages can +be stored without collapsing. That limit is currently 100. If the limit is reached, +all stored messages are discarded. Then when the device is back online, it receives +a special message indicating that the limit was reached. The application can then +handle the situation properly, typically by requesting a full sync. +<br><br> +Likewise, there is a limit on how many <code>collapse_key</code>s you can have for +a particular device. GCM allows a maximum of 4 different collapse keys to be used +by the GCM server per device +any given time. In other words, the GCM server can simultaneously store 4 different +send-to-sync messages, each with a different collapse key. If you exceed this number +GCM will only keep 4 collapse keys, with no guarantees about which ones they will be. +See <a href="#s2s">Send-to-sync messages</a> for more information. +</p> + +<p>If the device is not connected to GCM, the message will be stored until a +connection is established (again respecting the collapse key rules). When a connection +is established, GCM will deliver all pending messages to the device, regardless of +the <code>delay_while_idle</code> flag. If the device never gets connected again +(for instance, if it was factory reset), the message will eventually time out and +be discarded from GCM storage. The default timeout is 4 weeks, unless the +<code>time_to_live</code> flag is set.</p> + +<p>Finally, when GCM attempts to deliver a message to the device and the +application was uninstalled, GCM will discard that message right away and +invalidate the registration ID. Future attempts to send a message to that device +will get a <code>NotRegistered</code> error. See <a href="#unreg"> +How Unregistration Works</a> for more information.</p> +<p>Although is not possible to track the status of each individual message, the +Google Cloud Console stats are broken down by messages sent to device, messages +collapsed, and messages waiting for delivery.</p> + +<h3 id="throttling">Throttling</h3> +<p>To prevent abuse (such as sending a flood of messages to a device) and +to optimize for the overall network efficiency and battery life of +devices, GCM implements throttling of messages using a token bucket +scheme. Messages are throttled on a per application and per <a href="#collapsible">collapse +key</a> basis (including non-collapsible messages). Each application +collapse key is granted some initial tokens, and new tokens are granted +periodically therefter. Each token is valid for a single message sent to +the device. If an application collapse key exhausts its supply of +available tokens, new messages are buffered in a pending queue until +new tokens become available at the time of the periodic grant. Thus +throttling in between periodic grant intervals may add to the latency +of message delivery for an application collapse key that sends a large +number of messages within a short period of time. Messages in the pending +queue of an application collapse key may be delivered before the time +of the next periodic grant, if they are piggybacked with messages +belonging to a non-throttled category by GCM for network and battery +efficiency reasons.</p> -<ol> - <li>The system receives the incoming message and extracts the raw key/value -pairs from the message payload, if any.</li> - <li>The system passes the key/value pairs to the targeted Android application -in a <code>com.google.android.c2dm.intent.RECEIVE</code> Intent as a set of -extras.</li> - <li>The Android application extracts the raw data -from the <code>com.google.android.c2dm.intent.RECEIVE</code><code> </code>Intent -by key and processes the data.</li> -</ol> -<p>See the documentation for each connection server for more detail on how it -handles responses.</p> |