From f1598d1852e0c35db6bad40da162eca15680077e Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Tue, 17 Mar 2015 15:46:15 -0700 Subject: Changes for a quick, pre-migration bug sprint: Bug: 19679070, 19716684, 19680472. Change-Id: I14ba1cf53ea42cd7739793fd9873e40e4a2ee6a0 --- docs/html/google/gcm/ccs.jd | 136 +++++++++++----------- docs/html/google/gcm/gcm.jd | 2 +- docs/html/google/gcm/http.jd | 223 ++++++------------------------------- docs/html/google/gcm/server-ref.jd | 3 +- 4 files changed, 106 insertions(+), 258 deletions(-) (limited to 'docs/html/google/gcm') diff --git a/docs/html/google/gcm/ccs.jd b/docs/html/google/gcm/ccs.jd index 143b057..c4d1b1d 100644 --- a/docs/html/google/gcm/ccs.jd +++ b/docs/html/google/gcm/ccs.jd @@ -13,16 +13,14 @@ page.title=GCM Cloud Connection Server (XMPP)
  • Authentication
    • -
  • Message Format +
  • Downstream Messages
    1. Request format
    2. Response format
      3. +
    3. Receive delivery receipts
  • Upstream Messages -
      -
    1. Receive delivery receipts
      2. -
  • Flow Control
  • Implementing an XMPP-based App Server @@ -138,7 +136,7 @@ mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

    Server

    <success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
    -

    Message Format

    +

    Downstream Messages

    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:

    @@ -169,7 +167,8 @@ 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, -CCS will just resend it. +CCS resends it the next time a new XMPP connection is established, unless the +message expires first.

    CCS also sends an ACK or NACK for each server-to-device message. If you do not receive either, it means that the TCP connection was closed in the middle of the @@ -316,7 +315,7 @@ connection, but allowing whatever is already in the pipeline to continue. When y 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.

    +ACKing them)—CCS handles initiating a connection close when it is ready.

    The {@code CONNECTION_DRAINING} message looks like this:

    <message>
@@ -330,66 +329,11 @@ ACKing them)—CCS will handle initiating a connection close when it is read
 
 
    {@code CONNECTION_DRAINING} is currently the only {@code control_type} supported.
    
 
-
    Upstream Messages
    
-
-
    Using CCS and the
-
-{@code GoogleCloudMessaging}
-API, you can send messages from a user's device to the cloud.
    
-
-
    Here is how you send an upstream message using the
-
-{@code GoogleCloudMessaging}
-API. For a complete example, see Implementing GCM Client:
    
-
-
    GoogleCloudMessaging gcm = GoogleCloudMessaging.get(context);
-String GCM_SENDER_ID = "Your-Sender-ID";
-AtomicInteger msgId = new AtomicInteger();
-String id = Integer.toString(msgId.incrementAndGet());
-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 24 hours.
-int ttl = [0 seconds, 24 hours]
-
-gcm.send(GCM_SENDER_ID + "@gcm.googleapis.com", id, ttl, data);
-
    
-
-
    This call generates the necessary XMPP stanza for sending the upstream message.
-The message goes from the app on the device to CCS to the 3rd-party app server.
-The stanza has the following format:
    
-
-
    <message id="">
-  <gcm xmlns="google:mobile:data">
-  {
-      "category":"com.example.yourapp", // to know which app sent it
-      "data":
-      {
-          "hello":"world",
-      },
-      "message_id":"m-123",
-      "from":"REGID"
-  }
-  </gcm>
-</message>
    
-
-
    Here is the format of the ACK expected by CCS from 3rd-party app servers in
-response to the above message:
    
-
-
    <message id="">
-  <gcm xmlns="google:mobile:data">
-  {
-      "to":"REGID",
-      "message_id":"m-123"
-      "message_type":"ack"
-  }
-  </gcm>
-</message>
    
+
 
 
    Receive delivery receipts
    
 
-
    You can use upstream messaging to get delivery receipts (sent from CCS to
+
    You can get delivery receipts (sent from CCS to
 your 3rd party app server) when
 a device confirms that it received a message sent by CCS.
    
 
@@ -452,8 +396,68 @@ app server that a device received a message that CCS sent it:
    
 which in this example is {@code dr2:m-1366082849205}.
  • The original message ID, the device registration ID, and the status are inside the {@code "data"} field.
    • +
  • If the connection between CCS and the device is poor, GCM may send multiple, duplicate delivery + receipts. You can safely ignore such duplicates.
    • +

    Upstream Messages

    + +

    Using CCS and the + +{@code GoogleCloudMessaging} +API, you can send messages from a user's device to the cloud.

    + +

    Here is how you send an upstream message using the + +{@code GoogleCloudMessaging} +API. For a complete example, see Implementing GCM Client:

    + +
    GoogleCloudMessaging gcm = GoogleCloudMessaging.get(context);
+String GCM_SENDER_ID = "Your-Sender-ID";
+AtomicInteger msgId = new AtomicInteger();
+String id = Integer.toString(msgId.incrementAndGet());
+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 24 hours.
+int ttl = [0 seconds, 24 hours]
+
+gcm.send(GCM_SENDER_ID + "@gcm.googleapis.com", id, ttl, data);
+
    + +

    This call generates the necessary XMPP stanza for sending the upstream message. +The message goes from the app on the device to CCS to the 3rd-party app server. +The stanza has the following format:

    + +
    <message id="">
+  <gcm xmlns="google:mobile:data">
+  {
+      "category":"com.example.yourapp", // to know which app sent it
+      "data":
+      {
+          "hello":"world",
+      },
+      "message_id":"m-123",
+      "from":"REGID"
+  }
+  </gcm>
+</message>
    + +

    Here is the format of the ACK expected by CCS from 3rd-party app servers in +response to the above message:

    + +
    <message id="">
+  <gcm xmlns="google:mobile:data">
+  {
+      "to":"REGID",
+      "message_id":"m-123"
+      "message_type":"ack"
+  }
+  </gcm>
+</message>
    + +

    Flow Control

    Every message sent to CCS receives either an ACK or a NACK response. Messages @@ -468,7 +472,7 @@ figure 1:

    Figure 1. Message/ack flow.

    -

    Conversely, to avoid overloading the 3rd-party app server, CCS will stop sending +

    Conversely, to avoid overloading the 3rd-party app server, CCS stops sending 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 @@ -663,7 +667,7 @@ public class SmackCcsClient { * Creates a JSON encoded GCM message. * * @param to RegistrationId of the target device (Required). - * @param messageId Unique messageId for which CCS will send an + * @param messageId Unique messageId for which CCS sends an * "ack/nack" (Required). * @param payload Message content intended for the application. (Optional). * @param collapseKey GCM collapse_key parameter (Optional). diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index 4e345b3..d4bb45e 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -279,7 +279,7 @@ receives match the logged in user.

    How unregistration works

    -

    An app can be automatically unregistered after it is uninstalled. +

    A client app can be automatically unregistered after it is uninstalled. However, this process does not happen right away. What happens in this scenario is as follows:

      diff --git a/docs/html/google/gcm/http.jd b/docs/html/google/gcm/http.jd index 5022e09..e36440a 100644 --- a/docs/html/google/gcm/http.jd +++ b/docs/html/google/gcm/http.jd @@ -83,6 +83,32 @@ See the Server Reference for a list of all the parameters your JSON or plain text message can contain.

      +

      Checking the validity of an API key

      + +

      If you receive authentication errors when sending messages, check the validity +of your API key. For example, on Android, run the following command:

      + +
      # api_key=YOUR_API_KEY
+
+# curl --header "Authorization: key=$api_key" \
+       --header Content-Type:"application/json" \
+       https://android.googleapis.com/gcm/send \
+       -d "{\"registration_ids\":[\"ABC\"]}"
      + +

      +If you receive a 401 HTTP status code, your API key is not valid. Otherwise you +should see something like this:

      + +
      +{"multicast_id":6782339717028231855,"success":0,"failure":1,
+"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}
+
      + +

      +If you want to confirm the validity of a registration ID, you can do so by +replacing "ABC" with the registration ID. +

      +

      Request Format

      @@ -157,53 +183,10 @@ the body contains more information about the status of the message (including po non-200 status code (such as 400, 401 or 5xx). -

      Interpreting a success response

      -

      When a JSON request is successful (HTTP status code 200), the response body -contains a JSON object with the following fields:

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldDescription
      multicast_idUnique ID (number) identifying the multicast message.
      successNumber of messages that were processed without an error.
      failureNumber of messages that could not be processed.
      canonical_idsNumber of results that contain a canonical registration ID. See -Advanced Topics for more discussion of this topic.
      resultsArray of objects representing the status of the messages processed. The -objects are listed in the same order as the request (i.e., for each registration -ID in the request, its result is listed in the same index in the response) and -they can have these fields:
      -
        -
      • message_id: String representing the message when it was -successfully processed.
        • -
      • registration_id: If set, means that GCM processed the -message but it has another canonical registration ID for that device, so sender -should replace the IDs on future requests (otherwise they might be rejected). -This field is never set if there is an error in the request. -
        • -
      • error: String describing an error that occurred while -processing the message for that recipient. The possible values are the same as -documented in the above table, plus "Unavailable" (meaning GCM servers -were busy and could not process the message for that particular recipient, so -it could be retried).
        • -
      +

      When a JSON request is successful (HTTP status code 200), the JSON object returned +contains the +Downstream HTTP message response body.

      +

      If the value of failure and canonical_ids is 0, it's not necessary to parse the remainder of the response. Otherwise, we recommend that you iterate through the results field and do the following for each object @@ -227,8 +210,9 @@ device, or the client app isn't configured to receive messages.

    1. Otherwise, there is something wrong in the registration ID passed in the request; it is probably a non-recoverable error that will also require removing -the registration from the server database. See Interpreting -an error response for all possible error values.
      2. +the registration from the server database. See +Downstream message error response + codes for all possible error values. @@ -260,147 +244,6 @@ error code, they would have returned a 500 HTTP status instead). -

      Interpreting an error response

      -

      Here are the recommendations for handling the different types of error that -might occur when trying to send a message to a device:

      - -
      -
      Missing Registration ID
      -
      Check that the request contains a registration ID (either in the -registration_id parameter in a plain text message, or in the -registration_ids field in JSON). -
      Happens when error code is MissingRegistration.
      - -
      Invalid Registration ID
      -
      Check the formatting of the registration ID that you pass to the server. Make -sure it matches the registration ID the client app receives and that you're -not truncating it or adding additional characters. -
      Happens when error code is InvalidRegistration.
      - -
      Mismatched Sender
      -
      A registration ID is tied to a certain group of senders. When an application -registers for GCM usage, it must specify which senders are allowed to send messages. -Make sure you're using one of those when trying to send messages to the device. -If you switch to a different sender, the existing registration IDs won't work. -Happens when error code is MismatchSenderId.
      - -
      Unregistered Device
      -
      An existing registration ID may cease to be valid in a number of scenarios, including: -
        -
      • If the application manually unregisters.
        • -
      • If the application is automatically unregistered, which can happen -(but is not guaranteed) if the user uninstalls the application.
        • -
      • If the registration ID expires. Google might decide to refresh registration -IDs.
        • -
      • If the application is updated but the new version is not configured to receive -messages.
        • -
      -For all these cases, you should remove this registration ID from the 3rd-party -server and stop using it to send -messages. -
      Happens when error code is NotRegistered.
      - -
      Message Too Big
      -
      The total size of the payload data that is included in a message can't -exceed 4096 bytes. Note that this includes both the size of the keys as well -as the values. -
      Happens when error code is MessageTooBig.
      - -
      Invalid Data Key
      -
      The payload data contains a key (such as from or any value -prefixed by google.) that is used internally by GCM and therefore cannot be used. -Note that some words (such as collapse_key) are also used by GCM -but are allowed in the payload, in which case the payload value will be -overridden by the GCM value. -
      -Happens when the error code is InvalidDataKey.
      - -
      Invalid Time To Live
      -
      The value for the Time to Live field must be an integer representing -a duration in seconds between 0 and 2,419,200 (4 weeks). Happens when error code -is InvalidTtl. -
      - -
      Authentication Error
      -
      The sender account that you're trying to use to send a message couldn't be -authenticated. Possible causes are:
        -
      • Authorization header missing or with invalid syntax.
        • -
      • Invalid project number sent as key.
        • -
      • Key valid but with GCM service disabled.
        • -
      • Request originated from a server not whitelisted in the Server Key IPs.
        • - -
      -When there is an Authentication Error, you can check the validity of your API key by running You can check the validity -of your API key by running the following command (this example shows what you -would do on Android; see the documentation for your platform):
      - -
      # api_key=YOUR_API_KEY
-
-# curl --header "Authorization: key=$api_key" --header Content-Type:"application/json" https://android.googleapis.com/gcm/send  -d "{\"registration_ids\":[\"ABC\"]}"
      - - - -If you receive a 401 HTTP status code, your API key is not valid. Otherwise you -should see something like this:
      - -
      -{"multicast_id":6782339717028231855,"success":0,"failure":1,"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}
-
      -If you want to confirm the validity of a registration ID, you can do so by -replacing "ABC" with the registration ID. -
      -Happens when the HTTP status code is 401. - -
      Timeout
      - -
      The server couldn't process the request in time. You should retry the -same request, but you MUST obey the following requirements: - -
        - -
      • Honor the Retry-After header if it's included in the response -from the GCM server.
        • - - -
      • Implement exponential back-off in your retry mechanism. This means an -exponentially increasing delay after each failed retry (e.g. if you waited one -second before the first retry, wait at least two second before the next one, -then 4 seconds and so on). If you're sending multiple messages, delay each one -independently by an additional random amount to avoid issuing a new request for -all messages at the same time.
        • - - -Senders that cause problems risk being blacklisted. -
        -Happens when the HTTP status code is between 501 and 599, or when the -error field of a JSON object in the results array is Unavailable. -
      - -
      Internal Server Error
      - -
      -The server encountered an error while trying to process the request. You -could retry the same request (obeying the requirements listed in the Timeout -section), but if the error persists, please report the problem to Google. -
      -Happens when the HTTP status code is 500, or when the error field of a JSON -object in the results array is InternalServerError. -
      - -
      Invalid Package Name
      - -
      -A message was addressed to a registration ID whose package name did not match -the value passed in the request. Happens when error code is -InvalidPackageName. -
      - -
      Device Message Rate Exceeded
      -
      The rate of messages to a particular device is too high. You should reduce the number -of messages sent to this device and should not retry sending to this device immediately. -
      Happens when error code is DeviceMessageRateExceeded.
      - -

      Example responses

      This section shows a few examples of responses indicating messages that were diff --git a/docs/html/google/gcm/server-ref.jd b/docs/html/google/gcm/server-ref.jd index a94e727..2a41e58 100644 --- a/docs/html/google/gcm/server-ref.jd +++ b/docs/html/google/gcm/server-ref.jd @@ -665,7 +665,8 @@ matches the value passed in the request. Check that the token you're sending inside the Authentication header is the correct API key associated with your project. See -GCM HTTP Connection Server for details. +Checking the validity of an API Key + for details. Mismatched Sender -- cgit v1.1