From b642f672f00986106dfde4dbfa3fc7851c9a9622 Mon Sep 17 00:00:00 2001
From: Katie McCormick Note: To try out this feature, sign up using
this form. The GCM Cloud Connection Server (CCS) is a connection server based on XMPP.
-CCS allows 3rd-party app servers (which you're
-responsible for implementing) to communicate
-with Android devices by establishing a persistent TCP connection with Google
-servers using the XMPP protocol. This communication is asynchronous and bidirectional. 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
+your users' GCM-connected devices. You can continue to use the HTTP request mechanism to send messages to GCM
servers, side-by-side with CCS which uses XMPP. Some of the benefits of CCS include:In this document
-
@@ -73,22 +74,34 @@ APIs. For examples, see
Implementing GCM Server for a list of all the message
parameters and which connection server(s) supports them.
CCS just uses XMPP as an authenticated transport layer, so you can use most +XMPP libraries to manage the connection. For an example, see +Java sample using the Smack library.
-GCM Cloud Connection Server (CCS) is an XMPP endpoint, running on -{@code http://gcm.googleapis.com} port 5235.
+The CCS XMPP endpoint runs at {@code gcm.googleapis.com:5235}. When testing +functionality (with non-production users), you should instead connect to +{@code gcm-staging.googleapis.com:5236} (note the different port). Testing on +staging (a smaller environment where the latest CCS builds run) is beneficial +both for isolating real users from test code, as well as for early detection of +unexpected behavior changes.
-CCS requires a Transport Layer Security (TLS) connection. That means the XMPP -client must initiate a TLS connection. -For example in Java, you would call {@code setSocketFactory(SSLSocketFactory)}.
+The connection has two important requirements:
-CCS requires a SASL PLAIN authentication mechanism using -{@code <your_GCM_Sender_Id>@gcm.googleapis.com} (GCM sender ID) and the -API key as the password, where the sender ID and API key are the same as described -in Getting Started.
+You can use most XMPP libraries to interact with CCS.
+If at any point the connection fails, you should immediately reconnect. +There is no need to back off after a disconnect that happens after +authentication.
<str:features xmlns:str="http://etherx.jabber.org/streams"> - <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> - <mechanism>X-OAUTH2</mechanism> - <mechanism>X-GOOGLE-TOKEN</mechanism> - <mechanism>PLAIN</mechanism> - </mechanisms> + <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> + <mechanism>X-OAUTH2</mechanism> + <mechanism>X-GOOGLE-TOKEN</mechanism> + <mechanism>PLAIN</mechanism> + </mechanisms> </str:features>@@ -118,16 +131,18 @@ mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>
<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
CCS uses normal XMPP <message> stanzas. The body of the message must be:
-
Once the XMPP connection is established, CCS and your server use normal XMPP
+<message> stanzas to send JSON-encoded messages back and
+forth. The body of the <message> must be:
<gcm xmlns:google:mobile:data>
JSON payload
</gcm>
-The JSON payload for server-to-device is similar to what the GCM http endpoint -uses, with these exceptions:
+The JSON payload for regular GCM messages is similar to +what the GCM http endpoint uses, with these +exceptions:
message_type = ('ack');
- In addition to regular GCM messages, control messages are sent, indicated by +the {@code message_type} field in the JSON object. The value can be either +'ack' or 'nack', or 'control' (see formats below). Any GCM message with an +unknown {@code message_type} can be ignored by your server.
+For each device message your app server receives from CCS, it needs to send an ACK message. It never needs to send a NACK message. If you don't send an ACK for a message, @@ -251,7 +265,9 @@ message is "nack". A NACK message contains:
</message> -The following table lists some of the more common NACK error codes.
+The following table lists NACK error codes. Unless otherwise +indicated, a NACKed message should not be retried. Unexpected NACK error codes +should be treated the same as {@code INTERNAL_SERVER_ERROR}.
Table 1. NACK error codes.
@@ -262,8 +278,17 @@ message is "nack". A NACK message contains:Periodically, CCS needs to close down a connection to perform load balancing. Before it +closes the connection, CCS sends a {@code CONNECTION_DRAINING} message to indicate that the connection is being drained +and will be closed soon. "Draining" refers to shutting off the flow of messages coming into a +connection, but allowing whatever is already in the pipeline to continue. When you receive +a {@code CONNECTION_DRAINING} message, you should immediately begin sending messages to another CCS +connection, opening a new connection if necessary. You should, however, keep the original +connection open and continue receiving messages that may come over the connection (and +ACKing them)—CCS will handle initiating a connection close when it is ready.
+ +The {@code CONNECTION_DRAINING} message looks like this:
+<message>
+ <data:gcm xmlns:data="google:mobile:data">
+ {
+ "message_type":"control"
+ "control_type":"CONNECTION_DRAINING"
+ }
+ </data:gcm>
+</message>
+
+{@code CONNECTION_DRAINING} is currently the only {@code control_type} supported.
Every message sent to CCS receives either an ACK or a NACK response. Messages that haven't received one of these responses are considered pending. If the pending -message count reaches 1000, the 3rd-party app server should stop sending new messages +message count reaches 100, the 3rd-party app server should stop sending new messages and wait for CCS to acknowledge some of the existing pending messages as illustrated in figure 1:
@@ -395,7 +437,7 @@ figure 1: if there are too many unacknowledged messages. Therefore, the 3rd-party app server should "ACK" upstream messages, received from the client application via CCS, as soon as possible to maintain a constant flow of incoming messages. The aforementioned pending message limit doesn't -apply to these ACKs. Even if the pending message count reaches 1000, the 3rd-party app server +apply to these ACKs. Even if the pending message count reaches 100, the 3rd-party app server should continue sending ACKs for messages received from CCS to avoid blocking delivery of new upstream messages. @@ -795,7 +837,7 @@ USERNAME = "Your GCM Sender Id" PASSWORD = "API Key" REGISTRATION_ID = "Registration Id of the target device" -unacked_messages_quota = 1000 +unacked_messages_quota = 100 send_queue = [] # Return a random alphanumerical id diff --git a/docs/html/images/gcm/CCS-ack.png b/docs/html/images/gcm/CCS-ack.png index bce2ab2f5a1d96dbcf97ec4b966499ed4510a982..4633157a7067372111b1f973a60636b070f3431d 100644 GIT binary patch literal 54832 zcmd43WmKF?(>97EKwz-oZb@(kcMA{*?(Xgm!QF$qySux)TX1)GcQ`}#exCRJzID$3 z!&1B28;N@vQM#
z+AK}(^bP70SHdb~!{$WDQUAFJVLV kSSi6@iJ(1$YCp1e^L7HI=&f9|>UYraJNI~7=@us`9
zQ?@`{2LKwvpW2i{BTcSY^^dxeB?YR23>{L3oUj$xokq `1sZkc@^YHV9K%;(dL?kd`usNJl^O103!eHZBM66$*N<^(aGLBxC
zmNB%OR@a4`owvMThQsI90=xO >A^RZe
zjjuCit*1rb%~Kw8+yMxSK2Y0-0c=A4Hxfl;pTE-^6(@pnnP8SJe*f0!><(s@jzpyWCB_9eIex!e1ET_GI;$U$xR5v8!izf^h!a~?|JGMajJZ`J$RMdv
zf`=0G3vU3F_n8-cI;sH~DJBh*Re4+TW8T~I#aP#N%zOGy?;Nb=&kKi
lud0pAEBRVim5~xY9q;&u^fET2+O;Nt&8CV0G@c
z6X&