Merge "Doc changes: misc GCM updates." into jb-dev-docs

Author: labtopia

docs/html/guide/google/gcm/adv.jd

@@ -164,7 +164,7 @@ registerReceiver(mRetryReceiver, filter);
 <p>There are two ways to unregister a device from GCM: manually and automatically.</p>
 <p>An Android application can manually unregister itself by issuing a <code>com.google.android.c2dm.intent.UNREGISTER</code> intent, which is useful when the application offers a logoff feature (so it can unregister on logoff and register again on logon). See the <a href="gcm.html#unregistering">Architectural Overview</a> for more discussion of this topic. This is the sequence of events when an application unregisters itself:</p>
 <ol>
-  <li> The application issues a <code>com.google.android.c2dm.intent.UNREGISTER</code> intent, passing the registration ID (the application should have saved its registration ID when it received the proper <code>com.google.android.c2dm.intent.REGISTRATION</code> intent).</li>
+  <li> The application issues a <code>com.google.android.c2dm.intent.UNREGISTER</code> intent, passing the package name as an extra.</li>
   <li>When the GCM server is done with the unregistration, it sends a <code>com.google.android.c2dm.intent.REGISTRATION</code> intent with the <code>unregistered</code> extra set.</li>
   <li>The application then must contact the 3rd-party server so it can remove the registration ID.</li>
   <li>The application should also clear its registration ID.
@@ -175,7 +175,7 @@ registerReceiver(mRetryReceiver, filter);
   <li>The end user uninstalls the application.</li>
   <li>The 3rd-party server sends a message to GCM server.</li>
   <li>The GCM server sends the message to the device.</li>
-  <li>The GCM client receives the message and queries Package Manager about whether there are broadcast receivers configured to receive it, which returns <code>false</code>.
+  <li>The GCM client receives the message and queries Package Manager about whether there are broadcast receivers configured to receive it, which returns <code>false</code>. 
 </li>
   <li>The GCM client informs the GCM server that the application was uninstalled.</li>
   <li>The GCM server marks the registration ID for deletion.</li>
@@ -184,6 +184,9 @@ registerReceiver(mRetryReceiver, filter);
   <li>The 3rd-party deletes the registration ID.
   </li>
 </ol>
+
+<p class ="note"><strong>Note:</strong> The GCM client is the Google Cloud Messaging framework present on the device.</p>
+
 <p>Note that it might take a while for the registration ID be completely removed from GCM. Thus it is possible that messages sent during step 7 above gets a valid message ID as response, even though the message will not be delivered to the device. Eventually, the registration ID will be removed and the server will get a <code>NotRegistered</code> error, without any further action being required from the 3rd-party server (this scenario happens frequently while an application is being developed and tested).</p>
 
 <h2 id="collapsible">Send-to-Sync  vs. Messages with Payload</h2>

docs/html/guide/google/gcm/gcm.jd

@@ -763,13 +763,8 @@ the HTTP response contains a non-200 status code (such as 400, 401, or 503).</p>
     <td>There was an error authenticating the sender account. <a href="#auth_error">Troubleshoot</a></td>
   </tr>
   <tr>
-    <td>500</td>
-    <td>There was an internal error in the GCM server while trying to process the request. <a href="#internal_error">Troubleshoot</a></td>
-  </tr>
-  <tr>
-    <td>503</td>
-    <td>Indicates that the server is temporarily unavailable (i.e., because of timeouts, etc ). Sender must retry later, honoring any <code>Retry-After</code> header
-      included in the response. Application servers must implement exponential back-off. The GCM server took too long to process the request. <a href="#internal_error">Troubleshoot</a></td>
+    <td>5xx</td>
+    <td>Errors in the 500-599 range (such as 500 or 503) indicate that there was an internal error in the GCM server while trying to process the request, or that the server is temporarily unavailable (for example, because of timeouts). Sender must retry later, honoring any <code>Retry-After</code> header included in the response. Application servers must implement exponential back-off. <a href="#internal_error">Troubleshoot</a></td>
   </tr>
 </table>
 
@@ -927,17 +922,15 @@ all messages at the same time.</li>
 
 Senders that cause problems risk being blacklisted. 
 <br />
-Happens when the HTTP status code is 503, or when the <code>error</code> field of a JSON object in the results array is <code>Unavailable</code>.
+Happens when the HTTP status code is between 501 and 599, or when the <code>error</code> field of a JSON object in the results array is <code>Unavailable</code>.
 </dd>
 
 <dt id="internal_error"><strong>Internal Server Error</strong></dt>
 
 <dd>
 The server encountered an error while trying to process the request. You
-could retry the same request (obeying the requirements listed in the <strong>Timeout</strong>
+could retry the same request (obeying the requirements listed in the <a href="#timeout">Timeout</a>
 section), but if the error persists, please report the problem in the <a href="https://groups.google.com/forum/?fromgroups#!forum/android-gcm">android-gcm group</a>.
-<br /> 
-Senders that cause problems risk being blacklisted. 
 <br />
 Happens when the HTTP status code is 500, or when the <code>error</code> field of a JSON
 object in the results array is <code>InternalServerError</code>.

docs/html/guide/google/gcm/gs.jd

@@ -138,7 +138,14 @@ page.title=GCM: Getting Started
 
 </ol>
 <p>This intent service will be called by the <code>GCMBroadcastReceiver</code> (which is is provided by GCM library), as shown in the next step. It must be a subclass of <code>com.google.android.gcm.GCMBaseIntentService</code>, must contain a public constructor, and should be named <code>my_app_package.GCMIntentService</code> (unless you use a subclass of <code>GCMBroadcastReceiver</code> that overrides the method used to name the service).</p>
-<h4><br>
+
+<p>The intent service must also define its sender ID(s). It does this as follows:</p>
+<ul>
+  <li>If the value is static, the service's default constructor should call <code>super(senderIds)</code>.</li>
+  <li>If the value is dynamic, the service should override the <code>getSenderIds()</code> method.</li>
+</ul>
+
+<h4>
   Step 3: Write the my_app_package.GCMIntentService class</h4>
 <p>Next write the <code>my_app_package.GCMIntentService</code> class, overriding the following callback methods (which are called by <code>GCMBroadcastReceiver</code>):<br>
 </p>