From eb1e7eac9f0e1e8ac68da736b9ed92c9729ede08 Mon Sep 17 00:00:00 2001 From: && repo sync -j8 Date: Thu, 18 Oct 2012 14:55:29 -0700 Subject: Doc change: GCM category & dry_run params Bug # 7171849 Change-Id: Ifde95a058fc90b777faf3d43d34a72b048e20126 --- docs/html/guide/google/gcm/adv.jd | 2 +- docs/html/guide/google/gcm/c2dm.jd | 6 +++--- docs/html/guide/google/gcm/demo.jd | 4 ++-- docs/html/guide/google/gcm/gcm.jd | 35 +++++++++++++++++++++++++++++++---- docs/html/guide/google/gcm/gs.jd | 2 +- 5 files changed, 38 insertions(+), 11 deletions(-) (limited to 'docs/html') diff --git a/docs/html/guide/google/gcm/adv.jd b/docs/html/guide/google/gcm/adv.jd index f01953b..640fb52 100644 --- a/docs/html/guide/google/gcm/adv.jd +++ b/docs/html/guide/google/gcm/adv.jd @@ -258,7 +258,7 @@ registerReceiver(mRetryReceiver, filter);

Receiving Messages from Multiple Senders

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.

-

To make this possible, all you need to do is have each sender generate its own project ID. 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.

+

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.

This code snippet illustrates this feature. Senders are passed as an intent extra in a comma-separated list:

Intent intent = new Intent(GCMConstants.INTENT_TO_GCM_REGISTRATION);
 intent.setPackage(GSF_PACKAGE);
diff --git a/docs/html/guide/google/gcm/c2dm.jd b/docs/html/guide/google/gcm/c2dm.jd
index ecc08c1..e80a41f 100644
--- a/docs/html/guide/google/gcm/c2dm.jd
+++ b/docs/html/guide/google/gcm/c2dm.jd
@@ -55,7 +55,7 @@ page.title=Migration
 
To use the GCM service, you need to obtain a Simple API Key from Google APIs console page. For more information, see Getting Started. Note that GCM only accepts Simple API Key—using ClientLogin or OAuth2 tokens will not work.
 

 
Sender ID

-
In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project ID that you acquire from the API console, as described in Getting Started. 

+
In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project number that you acquire from the API console, as described in Getting Started. 

 
 
JSON format

 
GCM HTTP requests support JSON format in addition to plain text. For more information, see the Architectural Overview.

@@ -82,12 +82,12 @@ page.title=Migration
 
C2DM and GCM are not interoperable. For example, you cannot post notifications from GCM to C2DM registration IDs, nor can you use C2DM registration IDs as GCM registration IDs. From your server-side application, you must keep keep track of whether a registration ID is from C2DM or GCM and use the proper endpoint. 

 
 
As you transition from C2DM to GCM, your server needs to be aware of whether a given registration ID
-contains an old C2DM sender or a new GCM project ID. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.

+contains an old C2DM sender or a new GCM project number. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.

 
 
Migrating Your Apps

 
This section describes how to move existing C2DM apps to GCM.

 
Client changes

-
Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project ID generated when signing up for the new service. For example:

+
Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project number generated when signing up for the new service. For example:

 
Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER");
 // sets the app name in the intent
 registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0));
diff --git a/docs/html/guide/google/gcm/demo.jd b/docs/html/guide/google/gcm/demo.jd
index d66cbbc..7e35fd6 100644
--- a/docs/html/guide/google/gcm/demo.jd
+++ b/docs/html/guide/google/gcm/demo.jd
@@ -62,7 +62,7 @@ page.title=GCM Demo Application
 
For the Android application:

 
    
   
  • Emulator (or device) running Android 2.2 with Google APIs.
    • 
-  
  • The Google API project ID of the account registered to use GCM.
    • 
+  
  • The Google API project number of the account registered to use GCM.
    • 
 

 
Setting Up GCM

 
Before proceeding with the server and client setup, it's necessary to register a Google account with the Google API Console, enable Google Cloud Messaging in GCM, and obtain an API key from the Google API Console.

@@ -175,7 +175,7 @@ runserver:
 
 static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo";
 static final String SENDER_ID = "4815162342";

-
Note that the SERVER_URL is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (/). Also note that SENDER_ID is the Google API project ID you obtained in the server setup steps above.

+
Note that the SERVER_URL is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (/). Also note that SENDER_ID is the Google API project number you obtained in the server setup steps above.

 
   
  • In a shell window, go to the gcm-demo-client directory.
    • 
   
  • Use the SDK's android tool to generate the ant build files:
    • 
diff --git a/docs/html/guide/google/gcm/gcm.jd b/docs/html/guide/google/gcm/gcm.jd
index 1439437..04bf015 100644
--- a/docs/html/guide/google/gcm/gcm.jd
+++ b/docs/html/guide/google/gcm/gcm.jd
@@ -127,7 +127,7 @@ application server and sending them to the device. 
   
   
     Sender ID
-    A project ID you acquire from the API console, as described in Getting Started. The sender
+    A project number you acquire from the API console, as described in Getting Started. The sender
 ID is used in the registration process to identify an
 Android application that is permitted to send messages to the device.
   
@@ -354,7 +354,7 @@ could not run properly. 
 
    
 
 
      
-  
    • sender is the project ID of the account authorized to send messages
+  
    • sender is the project number of the account authorized to send messages
 to the Android application. 
      • 
   
    • app is the Android application's ID, set with a PendingIntent to
 allow the registration service to extract Android application information. 
      • 
@@ -667,6 +667,16 @@ sent. Optional. The default value is false, and must be a JSON bool
     time_to_live
     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). 
   
+
+  category
+  A string containing the package name of your application. When set, messages will only be sent to registration IDs that match the category. Optional.
+  
+
+
+  dry_run
+  If included, allows developers to test their request without actually sending a message. Optional. The default value is false, and must be a JSON boolean.
+  
+
 
 
 
      If you are using plain text instead of JSON, the message fields must be set as HTTP parameters sent in the body, and their syntax is slightly different, as described below:
@@ -696,9 +706,19 @@ sent. Optional. The default value is false, and must be a JSON bool
     time_to_live
     Same as JSON (see previous table). Optional.
   
+
+  category
+  Same as JSON (see previous table). Optional.
+  
+
+
+  dry_run
+  Same as JSON (see previous table). Optional.
+  
+
 
 
-
      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 parameter called dry_run with the value true. 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 fields (see Response format).
      
+
      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 dry_run with the value true. 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 fields (see Response format).
      
 
   
      Example requests
      
   
      Here is the smallest possible request (a message without any parameters and just one recipient) using JSON:
      
@@ -879,7 +899,7 @@ Happens when the error code is InvalidDataKey.
   
      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 ID sent as key.
        • 
+
      • 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.
        • 
 
@@ -936,6 +956,13 @@ Happens when the HTTP status code is 500, or when the error field o
 object in the results array is InternalServerError.
 
      
 
+
      Invalid Category
      
+
+
      
+A message was addressed to a registration ID whose category did not match the value passed in the request. Happens when error code is 
+InvalidCategory.
+
      
+
 
 
 
      Example responses
      
diff --git a/docs/html/guide/google/gcm/gs.jd b/docs/html/guide/google/gcm/gs.jd
index 0749279..beef281 100644
--- a/docs/html/guide/google/gcm/gs.jd
+++ b/docs/html/guide/google/gcm/gs.jd
@@ -41,7 +41,7 @@ page.title=GCM: Getting Started
 
 
       https://code.google.com/apis/console/#project:4815162342
      
 
-  
    •  Take note of the value after #project: (4815162342 in this example). This is your project ID, and it will be used later on as the GCM sender ID.
      • 
+  
    •  Take note of the value after #project: (4815162342 in this example). This is your project number, and it will be used later on as the GCM sender ID.
      • 
   
 
 
      Enabling the GCM Service
      
-- 
cgit v1.1