diff options
Diffstat (limited to 'docs/html/google/gcm/ccs.jd')
| -rw-r--r-- | docs/html/google/gcm/ccs.jd | 149 |
1 files changed, 110 insertions, 39 deletions
diff --git a/docs/html/google/gcm/ccs.jd b/docs/html/google/gcm/ccs.jd index 03addfd..4389e3d 100644 --- a/docs/html/google/gcm/ccs.jd +++ b/docs/html/google/gcm/ccs.jd @@ -19,7 +19,11 @@ page.title=GCM Cloud Connection Server (XMPP) <li><a href="#response">Response format</a></li> </ol> </li> - <li><a href="#upstream">Upstream Messages</a> </li> + <li><a href="#upstream">Upstream Messages</a> + <ol> + <li><a href="#receipts">Receive return receipts</a></li> + </ol> + </li> <li><a href="#flow">Flow Control</a> </li> <li><a href="#implement">Implementing an XMPP-based App Server</a> <ol class="toc"> @@ -43,9 +47,6 @@ target="_android">CCS and User Notifications Signup Form</a></li> </div> </div> -<p class="note"><strong>Note:</strong> To try out this feature, sign up using -<a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p> - <p>The GCM Cloud Connection Server (CCS) is an XMPP endpoint that provides a persistent, asynchronous, bidirectional connection to Google servers. The connection can be used to send and receive messages between your server and @@ -149,8 +150,8 @@ exceptions:</p> <li>CCS adds the field {@code message_id}, which is required. This ID uniquely identifies the message in an XMPP connection. The ACK or NACK from CCS uses the {@code message_id} to identify a message sent from 3rd-party app servers to CCS. -Therefore, it's important that this {@code message_id} not only be unique, but -always present.</li> +Therefore, it's important that this {@code message_id} not only be unique (per +sender ID), but always present.</li> </ul> <p>In addition to regular GCM messages, control messages are sent, indicated by @@ -188,7 +189,8 @@ parameters and which connection server(s) supports them.</p> "hello":"world", } "time_to_live":"600", - "delay_while_idle": true/false + "delay_while_idle": true/false, + "delivery_receipt_requested": true/false } </gcm> </message> @@ -227,42 +229,48 @@ message is "nack". A NACK message contains:</p> <p>Below are some examples.</p> <p>Bad registration:</p> + <pre><message> - <data:gcm xmlns:data="google:mobile:data"> + <gcm xmlns="google:mobile:data"> { - "error":"BAD_REGISTRATION", // error code + "message_type":"nack", "message_id":"msgId1", - "from":"PA91bHFOtaQGSwupt5l1og", - "message_type":"nack" + "from":"SomeInvalidRegistrationId", + "error":"BAD_REGISTRATION", + "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId" } - </data:gcm> + </gcm> </message></pre> -<p>Invalid "time to live":</p> +<p>Invalid JSON:</p> <pre><message> - <data:gcm xmlns:data="google:mobile:data"> - { - "error":"InvalidJson : INVALID_TTL : Invalid value (-1) for \"time_to_live\": must be between 0 and \"2419200\"\n", - "message_id":"msgId1", - "from":"APA91bHFOtaQGSwupt5l1og", - "message_type":"nack" - } - </data:gcm> -</message></pre> + <gcm xmlns="google:mobile:data"> + { + "message_type":"nack", + "message_id":"msgId1", + "from":"APA91bHFOtaQGSwupt5l1og", + "error":"INVALID_JSON", + "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc" + } + </gcm> +</message> +</pre> -<p>JSON type error:</p> +<p>Quota exceeded:</p> <pre><message> - <data:gcm xmlns:data="google:mobile:data"> - { - "error":"InvalidJson : JSON_TYPE_ERROR : Field \"delay_while_idle\" must be a JSON java.lang.Boolean: not-boolean-user-supplied-value\n", - "message_id":"msgId1", - "from":"APA91bHFOtaQGSwupt5l1og", - "message_type":"nack" - } - </data:gcm> -</message></pre> + <gcm xmlns="google:mobile:data"> + { + "message_type":"nack", + "message_id":"msgId1", + "from":"APA91bHFOtaQGSwupt5l1og", + "error":"QUOTA_EXCEEDED", + "error_description":"Short-term downstream quota exceeded for this registration id" + } + </gcm> +</message> +</pre> <p>The following table lists NACK error codes. Unless otherwise @@ -300,7 +308,7 @@ message should be immediately retried over another connection.</td> </tr> <tr> <td>{@code INVALID_JSON}</td> -<td>The JSON message payload was not valid.</td> +<td>The JSON message payload is not valid.</td> </tr> <tr> <td>{@code QUOTA_EXCEEDED}</td> @@ -309,10 +317,10 @@ sender/device pair) is too high. If you want to retry the message, try using a s rate.</td> </tr> <tr> -<td>{@code SERVICE_UNAVAILABLE}</td> -<td>CCS is not currently able to process the message. The -message should be retried over the same connection using exponential backoff -with an initial delay of 1 second.</td> + <td>{@code SERVICE_UNAVAILABLE}</td> + <td>CCS is not currently able to process the message. The + message should be retried over the same connection using exponential backoff + with an initial delay of 1 second.</td> </tr> </table> @@ -382,8 +390,8 @@ Bundle data = new Bundle(); // Bundle data consists of a key-value pair data.putString("hello", "world"); // "time to live" parameter -// This is optional. It specifies a value in seconds up to 4 weeks. -int ttl = [0 seconds, 4 weeks] +// This is optional. It specifies a value in seconds up to 24 hours. +int ttl = [0 seconds, 24 hours] gcm.send(GCM_SENDER_ID + "@gcm.googleapis.com", id, ttl, data); </pre> @@ -419,6 +427,69 @@ response to the above message:</p> </gcm> </message></pre> +<h3 id="receipts">Receive return receipts</h3> + +<p>You can use upstream messaging to get receipt notifications, confirming +that a given message was sent to a device. Your 3rd-party app server receives the receipt +notification from CCS once the message has been sent to the device.</p> + +<p>To enable this feature, the message your 3rd-party app server sends to CCS must include +a field called <code>"delivery_receipt_requested"</code>. When this field is set to +<code>true</code>, CCS sends a return receipt. Here is an XMPP stanza containing a JSON +message with <code>"delivery_receipt_requested"</code> set to <code>true</code>:</p> + +<pre><message id=""> + <gcm xmlns="google:mobile:data"> + { + "to":"REGISTRATION_ID", + "message_id":"m-1366082849205" + "data": + { + "hello":"world", + } + "time_to_live":"600", + "delay_while_idle": true, + <strong>"delivery_receipt_requested": true</strong> + } + </gcm> +</message> +</pre> + +<p>Here is an example of a receipt notification message that CCS sends back to your 3rd-party +app server:</p> + +</p> +<pre><message id=""> + <gcm xmlns="google:mobile:data"> + { + "category":"com.example.yourapp", // to know which app sent it + "data": + { + “message_status":"MESSAGE_SENT_TO_DEVICE", + “original_message_id”:”m-1366082849205” + “device_registration_id”: “REGISTRATION_ID” + }, + "message_id":"dr2:m-1366082849205", + "message_type":"receipt", + "from":"gcm.googleapis.com" + } + </gcm> +</message></pre> + +<p>Note the following:</p> + +<ul> + <li>The {@code "message_type"} is set to {@code "receipt"}. + <li>The {@code "message_status"} is set to {@code "MESSAGE_SENT_TO_DEVICE"}, + indicating that the message was delivered. Notice that in this case, +{@code "message_status"} is not a field but rather part of the data payload.</li> + <li>The receipt message ID consists of the original message ID, but with a +<code>dr:</code> prefix. Your 3rd-party app server must send an ACK back with this ID, +which in this example is {@code dr2:m-1366082849205}.</li> + <li>The original message ID and status are inside the +{@code "data"} field.</li> +</ul> + <h2 id="flow">Flow Control</h2> <p>Every message sent to CCS receives either an ACK or a NACK response. Messages |