From e89c6ebeceb2a04d8ee05e73e15a899b686f811a Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Wed, 28 May 2014 17:31:23 -0700 Subject: Doc update: GCM changes for I/O. Fixes for: b/15348323 b/15349955 b/15330953 Change-Id: Ie256a76ea83cf16256cded858531dd78b8da0558 --- docs/html/google/gcm/ccs.jd | 149 +++++++++++++++++++++-------- docs/html/google/gcm/client.jd | 3 +- docs/html/google/gcm/gcm.jd | 2 +- docs/html/google/gcm/index.jd | 39 +++++--- docs/html/google/gcm/notifications.jd | 129 +++++++++++++++++++++---- docs/html/google/gcm/server.jd | 3 +- docs/html/google/gcs/gcs-signup.jd | 10 ++ docs/html/google/gcs/index.jd | 30 ++++++ docs/html/google/index.jd | 10 ++ docs/html/images/google/datastore-logo.png | Bin 0 -> 10705 bytes docs/html/images/google/gcs-small.png | Bin 0 -> 1500 bytes docs/html/images/google/gcs.png | Bin 0 -> 95582 bytes 12 files changed, 300 insertions(+), 75 deletions(-) create mode 100644 docs/html/google/gcs/gcs-signup.jd create mode 100644 docs/html/google/gcs/index.jd create mode 100644 docs/html/images/google/datastore-logo.png create mode 100644 docs/html/images/google/gcs-small.png create mode 100644 docs/html/images/google/gcs.png (limited to 'docs/html') 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)
  • Response format
    • -
  • Upstream Messages
    • +
  • Upstream Messages +
      +
    1. Receive return receipts
      2. +
    +
  • Flow Control
  • Implementing an XMPP-based App Server
      @@ -43,9 +47,6 @@ target="_android">CCS and User Notifications Signup Form -

      Note: To try out this feature, sign up using -this form.

      -

      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:

    1. 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.
      2. +Therefore, it's important that this {@code message_id} not only be unique (per +sender ID), but always present.

      In addition to regular GCM messages, control messages are sent, indicated by @@ -188,7 +189,8 @@ parameters and which connection server(s) supports them.

      "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:

      Below are some examples.

      Bad registration:

      + 
      <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>
      -

      Invalid "time to live":

      +

      Invalid JSON:

      <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>
      + <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> + -

      JSON type error:

      +

      Quota exceeded:

      <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>
      + <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> +

      The following table lists NACK error codes. Unless otherwise @@ -300,7 +308,7 @@ message should be immediately retried over another connection. {@code INVALID_JSON} -The JSON message payload was not valid. +The JSON message payload is not valid. {@code QUOTA_EXCEEDED} @@ -309,10 +317,10 @@ sender/device pair) is too high. If you want to retry the message, try using a s rate. -{@code SERVICE_UNAVAILABLE} -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. + {@code SERVICE_UNAVAILABLE} + 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. @@ -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); @@ -419,6 +427,69 @@ response to the above message:

      </gcm> </message> +

      Receive return receipts

      + +

      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.

      + +

      To enable this feature, the message your 3rd-party app server sends to CCS must include +a field called "delivery_receipt_requested". When this field is set to +true, CCS sends a return receipt. Here is an XMPP stanza containing a JSON +message with "delivery_receipt_requested" set to true:

      + +
      <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,
+      "delivery_receipt_requested": true
+  }
+  </gcm>
+</message>
+
      + +

      Here is an example of a receipt notification message that CCS sends back to your 3rd-party +app server:

      + +

      +
      <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>
      + +

      Note the following:

      + +
        +
      • The {@code "message_type"} is set to {@code "receipt"}. +
      • 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.
        • +
      • The receipt message ID consists of the original message ID, but with a +dr: prefix. Your 3rd-party app server must send an ACK back with this ID, +which in this example is {@code dr2:m-1366082849205}.
        • +
      • The original message ID and status are inside the +{@code "data"} field.
        • +
      +

      Flow Control

      Every message sent to CCS receives either an ACK or a NACK response. Messages diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd index 42cebfc..ec7e748 100644 --- a/docs/html/google/gcm/client.jd +++ b/docs/html/google/gcm/client.jd @@ -246,7 +246,8 @@ private boolean checkPlayServices() {

      Register for GCM

      An Android application needs to register with GCM servers before it can receive messages. When an app registers, it receives a registration ID, which it can then -store for future use. In the following snippet the {@code onCreate()} method in the sample app's +store for future use (note that registration IDs must be kept secret). In the +following snippet the {@code onCreate()} method in the sample app's main activity checks to see if the app is already registered with GCM and with the server:

      diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index 88bf659..19151b9 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -123,7 +123,7 @@ it to receive messages. Once the Android application has the registration ID, it it to the 3rd-party application server, which uses it to identify each device that has registered to receive messages for a given Android application. In other words, a registration ID is tied to a particular Android application running on a particular -device. +device. Note that registration IDs must be kept secret.

      Note: If you use diff --git a/docs/html/google/gcm/index.jd b/docs/html/google/gcm/index.jd index 8f325b8..1f05a71 100644 --- a/docs/html/google/gcm/index.jd +++ b/docs/html/google/gcm/index.jd @@ -14,7 +14,10 @@ header.hide=1

      Google Cloud Messaging for Android

      Google Cloud Messaging for Android (GCM) is a service that allows you to send data -from your server to your users' Android-powered device, and also to receive messages from devices on the same connection. The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device. GCM is completely free no matter how big your messaging needs are, and there are no quotas. +from your server to your users' Android-powered device, and also to receive messages from +devices on the same connection. The GCM service handles all aspects of queueing of messages +and delivery to the target Android application running on the target device. GCM is +completely free no matter how big your messaging needs are, and there are no quotas.

      @@ -27,31 +30,39 @@ from your server to your users' Android-powered device, and also to receive mess

      This could be a lightweight message telling your app 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). GCM Architectural Overview.

      +up to 4kb of payload data (so apps like instant messaging can consume the message directly). +GCM Architectural Overview.

      Send "send-to-sync" messages

      -

      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. - Send-to-sync messages.

      - +

      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. + Learn more »

      Send messages with payload

      -

      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. - Messages with payload.

      +

      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. + Learn more »

      New Features

      -

      Faster, easier GCM setup

      -

      Streamlined registration makes it simple and fast to add GCM support to your Android app. Learn more »

      -

      Upstream messaging over XMPP

      -

      GCM's Cloud Connection Service (CCS) lets you communicate with Android devices over a persistent XMPP connection. The primary advantages of CCS are speed, and the ability to receive upstream messages (that is, messages from a device to the cloud). You can use the service in tandem with existing GCM APIs. Use this form to sign up for CCS. Learn more »

      -

      Seamless multi-device messaging

      -

      Maps a single user to a notification key, which you can then use to send a single message to multiple devices owned by the user. Use this form to sign up for User Notifications. Learn more »

      + + +

      Return Receipts

      +

      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. + Learn more »

      +

      Get Started

      -

      Get started using the new features with a tutorial that walks you through creating a GCM app. Learn more »

      +

      Get started with a tutorial that walks you through creating a GCM app. + Learn more »

      diff --git a/docs/html/google/gcm/notifications.jd b/docs/html/google/gcm/notifications.jd index 43a7368..2815f3d 100644 --- a/docs/html/google/gcm/notifications.jd +++ b/docs/html/google/gcm/notifications.jd @@ -14,8 +14,8 @@ page.title=User Notifications

      In this document

        -
      1. Request Format
        2. -
      2. Generate a Notification Key
        3. +
      3. Generate a Notification Key on the Server
        4. +
      4. Generate a Notification Key on the Client
      5. Add Registration IDs
      6. Remove Registration IDs
      7. Send Upstream Messages
        8. @@ -31,15 +31,11 @@ page.title=User Notifications
        1. Getting Started
          2. -
        2. CCS and User Notifications Signup Form
        -

        Note: To try out this feature, sign up using this form.

        - -

        With user notifications, 3rd-party app servers can send a single message to multiple instance of an app running on devices owned by a single user. This feature is called user notifications. User notifications make it possible for every @@ -76,27 +72,23 @@ and then reconciling it with the corresponding notification.

        You can use this feature with either the XMPP (CCS) or HTTP connection server.

        +

        You can generate notification keys in two different ways: on the server, and on +the client, if the user has a Google account. All of the associated registration IDs +can be mapped to a single user.

        The examples below show you how to perform generate/add/remove operations, and how to send upstream messages. For generate/add/remove operations, the message body is JSON.

        -

        Request Format

        -

        To send a message, the application server issues a POST request to -https://android.googleapis.com/gcm/notification.

        +

        Generate a Notification Key on the Server

        -

        Here is the HTTP request header you should use for all create/add/remove operations:

        - -
        content-type: "application/json"
-Header : "project_id": <projectID>
-Header: "Authorization", "key=API_KEY"
-
        - -

        Generate a Notification Key

        +

        To generate a notification key on the server, you create a new +create a new notification_key and map it to a +notification_key_name.

        This example shows how to create a new notification_key for a notification_key_name called appUser-Chris. -The {@code notification_key_name} is a name or identifier (can be a username for +The {@code notification_key_name} is a name or identifier (it 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. Note that notification_key_name and notification_key are unique to a group of registration IDs. It is also @@ -116,10 +108,109 @@ to use in subsequent operations:

        "registration_ids": ["4", "8", "15", "16", "23", "42"] } +

        Request format

        + +

        To send a message in cases where your notification key is generated on the server, +the application server issues a POST request to +https://android.googleapis.com/gcm/notification.

        + +

        Here is the HTTP request header you should use for all server side create/add/remove operations:

        + +
        content-type: "application/json"
+Header : "project_id": <projectID>
+Header: "Authorization", "key=API_KEY"
+
        + + +

        Generate a Notification Key on the Client

        + +

        Generating a notification key on the client is useful for cases where a server is unavailable. +To generate a notification key on the client, the device must have at least one +Google account. Note that the process for generating a notification key on the client is significantly +different from the server process described above.

        + +

        To generate a notification key on the client:

        + +
          +
        1. Open your project in the Google Developers Console.
          2. +
        2. Click APIS & AUTH > Credentials.
          3. +
        3. Under OAuth, click Create new Client ID.
          4. +
        4. In the Create Client ID dialog, select Web Application as +the application type, and click Create Client ID.
          5. +
        5. Copy the value from Client ID for web application > Client ID. +This client ID represents a Google account "scope" that you will use to generate an {@code id_token}.
          6. +
        + +

        Once you've followed the above steps and gotten a client ID from Google Developers Console, + you're ready to add this feature to your app. First check the device for the presence of a Google +account. For example:

        + +
        // This snippet takes the simple approach of using the first returned Google account,
+// but you can pick any Google account on the device.
+public String getAccount() {
+    Account[] accounts = AccountManager.get(getActivity()).
+        getAccountsByType("com.google");
+    if (accounts.length == 0) {
+        return null;
+    }
+    return accounts[0].name;
+}
        + +

        Next, get an authentication token ({@code id_token}) by using the GoogleAuthUtil +class. For example:

        + +
        String accountName = getAccount();
+
+// Initialize the scope using the client ID you got from the Console.
+final String scope = "audience:server:client_id:"
+        + "1262xxx48712-9qs6n32447mcj9dirtnkyrejt82saa52.apps.googleusercontent.com";
+String id_token = null;
+try {
+    id_token = GoogleAuthUtil.getToken(context, accountName, scope);
+} catch (Exception e) {
+    log("exception while getting id_token: " + e);
+}
+...
        + +

        Now use id_token to authenticate your request. +This add operation returns a {@code notification_key}. +Third parties must save this {@code notification_key} (as well as its mapping to the +notification_key_name) +to use in subsequent operations. Note that a client request only takes a single regID. +The only operations supported on the client side are add/remove.

        + +
        request:
+{
+   "operation": "add",
+   "notification_key_name": "appUser-Chris",
+   "registration_ids": ["4"]
+   "id_token": "id_token"
+}
        + +

        Request format

        + +

        To send a message in cases where your notification key is generated on the client, +the application server issues a POST request to +https://android.googleapis.com/gcm/googlenotification.

        + +

        Here is the HTTP request header you should use for all add/remove operations. The +client side doesn't support the create operation; +the add operation has the effect of creating the notification key if it doesn't already +exist:

        + +
        content-type: "application/json"
+Header : "project_id": <projectID>
+
        + +

        Note that the authentication token is passed in the JSON body as shown above, not the header. +This is different from the server case.

        + +

        Add Registration IDs

        This example shows how to add registration IDs for a given notification key. -The maximum number of members allowed for a {@code notification_key} is 10.

        +The maximum number of members allowed for a {@code notification_key} is 20.

        Note that the notification_key_name is not strictly required for adding/removing regIDs. But including it protects you against accidentally using diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd index ccd1267..e3a6b25 100644 --- a/docs/html/google/gcm/server.jd +++ b/docs/html/google/gcm/server.jd @@ -120,7 +120,8 @@ have an application server that meets the following criteria:

      8. Able to store the API key and client registration IDs. The API key is included in the header of POST requests that send messages.
        9. -
      9. Able to generate message IDs to uniquely identify each message it sends.
        10. +
      10. Able to generate message IDs to uniquely identify each message it sends. Message IDs +should be unique per sender ID.

        11. Sending Messages

        diff --git a/docs/html/google/gcs/gcs-signup.jd b/docs/html/google/gcs/gcs-signup.jd new file mode 100644 index 0000000..7334cec --- /dev/null +++ b/docs/html/google/gcs/gcs-signup.jd @@ -0,0 +1,10 @@ +page.title=Sign Up for Google Cloud Save + +@jd:body + +

        Sign up to be a trial partner for Google Cloud Save.

        + + + + + diff --git a/docs/html/google/gcs/index.jd b/docs/html/google/gcs/index.jd new file mode 100644 index 0000000..e5f4776 --- /dev/null +++ b/docs/html/google/gcs/index.jd @@ -0,0 +1,30 @@ +page.title=Google Cloud Save +page.tags="gcs" +header.hide=1 +@jd:body + + +
        + +
        + +
        +
        + +

        Google Cloud Save

        +

        + Google Cloud Save is a service that enables per-user data storage +and sync in your apps with no backend programming required. Google Cloud Save +stores its data +in Google Cloud Datastore, + a fully managed, schemaless database for storing non-relational data. Cloud +Datastore automatically scales with your users. +Google Cloud Save works even when your device is offline, and it +provides an easy transition to server-side coding because +the same database is accessible via App Engine and Compute Engine. +Finally, Google Cloud Save provides a generous initial per-user free quota that +expands as your user base grows. +

        +Sign Up +
        +
        diff --git a/docs/html/google/index.jd b/docs/html/google/index.jd index 2e97d62..4778a85 100644 --- a/docs/html/google/index.jd +++ b/docs/html/google/index.jd @@ -89,6 +89,16 @@ cloud messaging.

        to use Google Cloud Messaging.

        +
        +
        + +
        +

        Google Cloud Save

        +

        Enable per-user data storage and sync in your apps with no backend programming + required.

        +
        + diff --git a/docs/html/images/google/datastore-logo.png b/docs/html/images/google/datastore-logo.png new file mode 100644 index 0000000..a0fc0a0 Binary files /dev/null and b/docs/html/images/google/datastore-logo.png differ diff --git a/docs/html/images/google/gcs-small.png b/docs/html/images/google/gcs-small.png new file mode 100644 index 0000000..b8dbe0d Binary files /dev/null and b/docs/html/images/google/gcs-small.png differ diff --git a/docs/html/images/google/gcs.png b/docs/html/images/google/gcs.png new file mode 100644 index 0000000..7355d64 Binary files /dev/null and b/docs/html/images/google/gcs.png differ -- cgit v1.1