From 7cd6dcd2f80fbc3094ae4948f58dd897b89fd98e Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Tue, 3 Jul 2012 14:36:05 -0700 Subject: [PATCH] Doc update: GCM doc cleanup. Change-Id: Ie84a6ebdd12a05c8dbe1fff97539aea90c93554c --- docs/html/guide/google/gcm/c2dm.jd | 14 +++++++++++++- docs/html/guide/google/gcm/demo.jd | 16 ++++++++-------- docs/html/guide/google/gcm/gs.jd | 15 +++++++++++---- docs/html/guide/google/gcm/index.jd | 3 ++- 4 files changed, 34 insertions(+), 14 deletions(-) diff --git a/docs/html/guide/google/gcm/c2dm.jd b/docs/html/guide/google/gcm/c2dm.jd index fd1bb0c5a6dff..5974485f6967d 100644 --- a/docs/html/guide/google/gcm/c2dm.jd +++ b/docs/html/guide/google/gcm/c2dm.jd @@ -17,7 +17,11 @@ page.title=Migration
  1. Historical Overview
    2. -
  2. How is GCM Different from C2DM?
    3. +
  3. How is GCM Different from C2DM? +
      +
    1. Relationship between C2DM and GCM
      2. +
    +
  4. Migrating Your Apps
    1. Client changes
      2. @@ -72,6 +76,14 @@ page.title=Migration
      There may be situations where the server ends up with 2 registration IDs for the same device. If the GCM response contains a registration ID, simply replace the registration ID you have with the one provided. With this feature your application doesn't need to send the device ID to your server anymore. For more information, see Advanced Topics.

      GCM also provides helper libraries (client and server) to make writing your code easier.

      + +

      Relationship between C2DM and GCM

      + +

      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.

      +

      Migrating Your Apps

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

      Client changes

      diff --git a/docs/html/guide/google/gcm/demo.jd b/docs/html/guide/google/gcm/demo.jd index 2e1e9755180d6..4c56373a2f9c6 100644 --- a/docs/html/guide/google/gcm/demo.jd +++ b/docs/html/guide/google/gcm/demo.jd @@ -74,11 +74,11 @@ page.title=GCM Demo Application
    2. From the SDK Manager, install Extras > Google Cloud Messaging for Android Library. -

      This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.

      +

      This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-server, samples/gcm-demo-client, samples/gcm-demo-server, and samples/gcm-demo-appengine.

      3. -
    3. In a text editor, edit the gcm-demo-server/WebContent/WEB-INF/classes/api.key and replace the existing text with the API key obtained above.
      4. -
    4. In a shell window, go to the gcm-demo-server directory.
      5. +
    5. In a text editor, edit the samples/gcm-demo-server/WebContent/WEB-INF/classes/api.key and replace the existing text with the API key obtained above.
      6. +
    6. In a shell window, go to the samples/gcm-demo-server directory.
    7. Generate the server's WAR file by running ant war:
      8. $ ant war
@@ -112,13 +112,13 @@ Total time: 0 seconds
 
      To set up the server using a standard App Engine for Java:
      
 
        
   
      1.  From the SDK Manager, install Extras > Google Cloud Messaging for Android Library.
-    
        This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.
        
+    
        This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-server, samples/gcm-demo-client, samples/gcm-demo-server, and samples/gcm-demo-appengine.
        
   
        2. 
-  
      2. In a text editor, edit the gcm-demo-appengine/src/com/google/android/gcm/demo/server/ApiKeyInitializer.java and replace the existing text with the API key obtained above.
+  
      3. In a text editor, edit samples/gcm-demo-appengine/src/com/google/android/gcm/demo/server/ApiKeyInitializer.java and replace the existing text with the API key obtained above.
   
        Note: The API key value set in that class will be used just once to create a persistent entity on App Engine. If you deploy the application, you can use App Engine's Datastore Viewer to change it later.
        
   
   
        4. 
-  
      4. In a shell window, go to the gcm-api-server directory.
        5. 
+  
      5. In a shell window, go to the samples/gcm-demo-appengine directory.
        6. 
   
      6. Start the development App Engine server by ant runserver, using the -Dsdk.dir to indicate the location of the App Engine SDK and -Dserver.host to set your server's hostname or IP address:
        7. 
 
 
        @@ -163,9 +163,9 @@ runserver:
 
        To set up the device:
        
 
          
   
        1.  From the SDK Manager, install Extras > Google Cloud Messaging for Android Library.
-    
          This creates a gcm directory under YOUR_SDK_ROOT/extras/google containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, gcm-server, and source.properties.
          
+    
          This creates a gcm directory under YOUR_SDK_ROOT/extras/google containing these subdirectories: gcm-client, gcm-server, samples/gcm-demo-client, samples/gcm-demo-server, and samples/gcm-demo-appengine.
          
   
          2. 
-  
        2. Using a text editor, open  gcm-demo-client/src/com/google/android/gcm/demo/app/CommonUtilities.java and set the proper values for the SENDER_ID and SERVER_URL constants. For example:
          3. 
+  
        3. Using a text editor, open  samples/gcm-demo-client/src/com/google/android/gcm/demo/app/CommonUtilities.java and set the proper values for the SENDER_ID and SERVER_URL constants. For example:
          4. 
 
 
           static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo";
diff --git a/docs/html/guide/google/gcm/gs.jd b/docs/html/guide/google/gcm/gs.jd
index 5e426c2303b8a..8f05d30a5e6aa 100644
--- a/docs/html/guide/google/gcm/gs.jd
+++ b/docs/html/guide/google/gcm/gs.jd
@@ -85,7 +85,7 @@ page.title=GCM: Getting Started
 
          Note: If you need to rotate the key, click  Generate new key. A new key  will be created while the old one will still be active for up to 24 hours. If you want to get rid of the old key immediately (for example, if you feel it was compromised), click Delete key.
          
 
 
          Install the Helper Libraries
          
-
          To perform the steps described in the following sections, you must first install the helper libraries (reference: client and server). From the SDK Manager, install Extras > Google Cloud Messaging for Android Library. This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-demo-appengine, gcm-demo-client, gcm-demo-server, and gcm-server.
          
+
          To perform the steps described in the following sections, you must first install the helper libraries (reference: client and server). From the SDK Manager, install Extras > Google Cloud Messaging for Android Library. This creates a gcm directory under YOUR_SDK_ROOT/extras/google/ containing these subdirectories: gcm-client, gcm-server, samples/gcm-demo-client, samples/gcm-demo-server, and samples/gcm-demo-appengine.
          
 
          Writing the Android Application
          
 
          This section describes the steps involved in writing an Android application that uses GCM.
          
 
          Step 1: Copy the gcm.jar file into your application classpath
          
@@ -104,9 +104,16 @@ page.title=GCM: Getting Started
 
           This permission must be called my_app_package.permission.C2D_MESSAGE (where my_app_package is the package name of your app as defined by the manifest tag), otherwise it will not  work.
          
 
          Note: This permission is not required if you are targeting your application to 4.1 or above (i.e., minSdkVersion 16)
          
 
-  
        4. Add the permission to receive GCM messages:
          5. 
+  
        5. Add the following permissions:
          6. 
 
-
          <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
          
+
          <!-- App receives GCM messages. -->
+<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
+<!-- GCM connects to Google Services. -->
+<uses-permission android:name="android.permission.INTERNET" /> 
+<!-- GCM requires a Google account. -->
+<uses-permission android:name="android.permission.GET_ACCOUNTS" />
+<!-- Keeps the processor from sleeping when a message is received. -->
+<uses-permission android:name="android.permission.WAKE_LOCK" />
          
 
   
        6. Add the following broadcast receiver:
          7. 
 
@@ -127,7 +134,7 @@ page.title=GCM: Getting Started
  
          <service android:name=".GCMIntentService" />
          
 
 
        
-
         This intent service will be called by the GCMBroadcastReceiver (which is is provided by GCM library), as shown in the next step. It must be named my_app_package.GCMIntentService, unless you use a subclass of GCMBroadcastReceiver that overrides the method used to name the service.
        
+
        This intent service will be called by the GCMBroadcastReceiver (which is is provided by GCM library), as shown in the next step. It must be a subclass of com.google.android.gcm.GCMBaseIntentService, must contain a public constructor, and should be named my_app_package.GCMIntentService (unless you use a subclass of GCMBroadcastReceiver that overrides the method used to name the service).
        
 

        
   Step 3: Write the my_app_package.GCMIntentService class
        
 
        Next write the my_app_package.GCMIntentService class, overriding the following callback methods (which are called by GCMBroadcastReceiver):
        
diff --git a/docs/html/guide/google/gcm/index.jd b/docs/html/guide/google/gcm/index.jd
index cba8d0b19d0f3..140b0762967af 100644
--- a/docs/html/guide/google/gcm/index.jd
+++ b/docs/html/guide/google/gcm/index.jd
@@ -5,7 +5,7 @@ page.title=Google Cloud Messaging for Android
 
        
 
        Google Cloud Messaging for Android (GCM) is a service that helps developers send data from servers to their Android applications on Android devices. This could be a lightweight message telling the Android application that 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). The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device.
        
 
-
        To learn more about GCM, read the following documents:
        
+
        To learn more about GCM, you can join the android-gcm group and read the following documents:
        
 
 
        
   
        Getting Started
        
@@ -23,3 +23,4 @@ page.title=Google Cloud Messaging for Android
 
        GCM also provides helper libraries for client and server development.
        
 
 
+