page.title=Using the GCM Helper Libraries
page.tags=cloud,push,messaging
@jd:body

<div id="deprecatedSticker">
  <a href="#" 
     onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false">
    <strong>This doc is deprecated</strong></a>
</div>


<div id="naMessage" style="display:block">
<div><p><strong>The information in this document has been superseded by <a href="server.html">GCM Server</a> and <a href="client.html">GCM Client</a></strong>. Please use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">{@code GoogleCloudMessaging}</a> API instead of the GCM client helper library. The GCM server helper library is still valid.</p>

 <input style="margin-top:1em;padding:5px" type="button"
        value="That's nice, but I still want to read this document"
onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" />
</div>
</div>


<div id="qv-wrapper">
<div id="qv">

<h2>Quickview</h2>

<ul>
<li>Walk through the steps of creating a GCM app.</li>
</ul>


<h2>In this document</h2>

<ol class="toc">
<li><a href="#libs">Installing the Helper Libraries</a></li>
<li><a href="#android-app">Writing the Android Application</a>
<li><a href="#server-app">Writing the Server-side Application</a> </li>
</ol>

<h2>See Also</h2>

<ol class="toc">
<li><a href="{@docRoot}google/play-services/gcm/gs.html">Getting Started with GCM Extensions</a></li>
<li><a href="https://services.google.com/fb/forms/gcm/" class="external-link" target="_android">CCS and User Notifications Signup Form</a></li>
</ol>

</div>
</div>

<p>This document describes how to write an Android application and the  server-side logic, using the client and server <a href="{@docRoot}reference/com/google/android/gcm/package-summary.html">helper libraries</a> provided by GCM.</p> 

<p>The helper libraries are one option for creating an Android application that uses GCM. You can alternatively use the approach described in the <a href="{@docRoot}google/gcm/gcm.html#writing_apps">GCM Architectural Overview</a>. If you need to perform upstream messaging, you must use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> APIs, and <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> also provides a streamlined registration process.</p>

<p>For information on how to get started creating an Android GCM application and an example of how to use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">GoogleCloudMessaging</a> APIs, see <a href="{@docRoot}google/gcm/gs.html">Getting Started</a>.</p>

<h2 id="libs">Installing the Helper Libraries</h2>
<p>To perform the steps described in the following sections, you must first install the 
<a href="{@docRoot}reference/com/google/android/gcm/package-summary.html">helper libraries</a>. Note that while using the helper libraries is recommended, it is not required. See the <a href="gcm.html#writing_apps">GCM Architectural Overview</a> for a description of how to write apps without using the helper libraries.

<p>To install the helper libraries, choose 
<strong>Extras &gt; Google Cloud Messaging for Android Library</strong>
from the SDK Manager. This creates a <code>gcm</code> directory under
<code><em>YOUR_SDK_ROOT</em>/extras/google/</code> containing these
subdirectories: <code>gcm-client</code>, <code>gcm-server</code>,
<code>samples/gcm-demo-client</code>, <code>samples/gcm-demo-server</code>,
and <code>samples/gcm-demo-appengine</code>.</p>

<p class="note"><strong>Note:</strong> If you don't see <strong>Extras &gt; Google Cloud Messaging for Android Library</strong> in the SDK Manager, make sure you are running version 20 or higher. Be sure to restart the SDK Manager after updating it.</p>

<h2 id="android-app">Writing the Android Application</h2>
<p>This section describes the steps involved in writing an Android application that uses GCM.</p>
<h4>Step 1: Copy the gcm.jar file into your application classpath</h4>
<p> To write your Android application, first copy the <code>gcm.jar</code> file from the SDK's <code>gcm-client/dist</code> directory to your application classpath.</p>
<h4>Step 2: Make the following changes in the application's Android manifest</h4>
<ol>
  <li>GCM requires Android 2.2 or later, so if your application cannot work without GCM, add the following line, where <em>xx</em> is the latest target SDK version:</li>

<pre class="prettyprint pretty-xml">&lt;uses-sdk android:minSdkVersion=&quot;8&quot; android:targetSdkVersion=&quot;xx&quot;/&gt;</pre>

  <li>Declare and use a custom permission so only this application can receive GCM messages:<br>
  </li>

<pre class="prettyprint pretty-xml">&lt;permission android:name=&quot;my_app_package.permission.C2D_MESSAGE&quot; android:protectionLevel=&quot;signature&quot; /&gt;
&lt;uses-permission android:name=&quot;my_app_package.permission.C2D_MESSAGE&quot; /&gt; </pre>
<p> This permission must be called <code>my_app_package.permission.C2D_MESSAGE</code> (where <code>my_app_package</code> is the package name of your app as defined by the manifest tag), otherwise it will not  work.</p>
<p class="note"><strong>Note:</strong> This permission is not required if you are targeting your application to 4.1 or above (i.e., minSdkVersion 16)</p>

  <li>Add the following permissions:</li>

<pre class="prettyprint pretty-xml">&lt;!-- App receives GCM messages. --&gt;
&lt;uses-permission android:name=&quot;com.google.android.c2dm.permission.RECEIVE&quot; /&gt;
&lt;!-- GCM connects to Google Services. --&gt;
&lt;uses-permission android:name=&quot;android.permission.INTERNET&quot; /&gt; 
&lt;!-- GCM requires a Google account. --&gt;
&lt;uses-permission android:name=&quot;android.permission.GET_ACCOUNTS&quot; /&gt;
&lt;!-- Keeps the processor from sleeping when a message is received. --&gt;
&lt;uses-permission android:name=&quot;android.permission.WAKE_LOCK&quot; /&gt;</pre>

  <li>Add the following broadcast receiver:</li>

<pre class="prettyprint pretty-xml">&lt;receiver android:name=&quot;com.google.android.gcm.GCMBroadcastReceiver&quot; android:permission=&quot;com.google.android.c2dm.permission.SEND&quot; &gt;
  &lt;intent-filter&gt;
    &lt;action android:name=&quot;com.google.android.c2dm.intent.RECEIVE&quot; /&gt;
    &lt;action android:name=&quot;com.google.android.c2dm.intent.REGISTRATION&quot; /&gt;
    &lt;category android:name=&quot;my_app_package&quot; /&gt;
  &lt;/intent-filter&gt;
&lt;/receiver&gt;</pre>
<p> This broadcast receiver is responsible for handling the 2 intents that can be sent by GCM (<code>com.google.android.c2dm.intent.RECEIVE</code> and <code>com.google.android.c2dm.intent.REGISTRATION</code>) and should be defined in the manifest (rather than programmatically) so that these intents can be received even if the application is not running. By setting the <code>com.google.android.c2dm.permission.SEND</code> permission, you are ensuring that only intents sent by the GCM system framework are sent to the receiver (a regular application cannot issue intents with that permission).</p>
<p> Notice that <code>android:name</code> in the category tag must be replaced by your application's package name (and the category tag  is not required for applications targeted to minSdkVersion 16 and higher).<br>
  </p>

  <li>Add the following intent service:</li>


 <pre class="prettyprint pretty-xml">&lt;service android:name=&quot;.GCMIntentService&quot; /&gt;</pre>

</ol>
<p>This intent service will be called by the <code>GCMBroadcastReceiver</code> (which is provided by the 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>

<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>
<ul>
  <li><code>onRegistered(Context context, String regId)</code>: Called after a registration intent is received, passes the registration ID assigned by GCM to that device/application pair as parameter. Typically, you should send the <code>regid</code> to your server so it can use it to send messages to this device.</li>
  <li><code>onUnregistered(Context context, String regId)</code>: Called after the device has been unregistered from GCM. Typically, you should send the <code>regid</code> to the server so it unregisters the device.</li>
  <li><code>onMessage(Context context, Intent intent)</code>: Called when your server sends a message to GCM, and GCM delivers it to the device. If the message has a payload, its contents are available as extras in the intent.</li>
  <li><code>onError(Context context, String errorId)</code>: Called when the device tries to register or unregister, but GCM returned an error. Typically, there is nothing to be done other than evaluating the error (returned by errorId) and trying to fix the problem.</li>
  <li> <code>onRecoverableError(Context context, String errorId)</code>: Called when the device tries to register or unregister, but the GCM servers are unavailable. The GCM library will retry the operation using exponential backup, unless this method is overridden and returns false. This method is optional and should be overridden only if you want to display the message to the user or cancel the retry attempts. 
  </li>
</ul>

<p class="note"><strong>Note:</strong> The methods above run in the intent service's thread and hence are free to make network calls without the risk of blocking the UI thread.</p>

<h4> Step 4: Write your application's main activity</h4>
Add the following import statement in your application's main activity:
<pre class="prettyprint pretty-java">import com.google.android.gcm.GCMRegistrar;</pre>
<p> In the <code>onCreate()</code> method, add the following code:</p>
<pre class="prettyprint pretty-java">GCMRegistrar.checkDevice(this);
GCMRegistrar.checkManifest(this);
final String regId = GCMRegistrar.getRegistrationId(this);
if (regId.equals("")) {
  GCMRegistrar.register(this, SENDER_ID);
} else {
  Log.v(TAG, "Already registered");
}</pre>
<p>The <code>checkDevice()</code> method verifies that the device supports GCM and throws an exception if it does not (for instance, if it is an emulator that does not contain the Google APIs). Similarly, the <code>checkManifest()</code> method verifies that the application manifest contains meets all the requirements described in <a href="#android-app">Writing the Android Application</a> (this method is only necessary when you are developing the application; once the application is ready to be published, you can remove it).</p>

<p>Once the sanity checks are done, the device calls <code>GCMRegsistrar.register()</code> to register the device, passing the <code>SENDER_ID</code> you got when you signed up for GCM. But since the <code>GCMRegistrar</code> singleton keeps track of the registration ID upon the arrival of registration intents, you can call <code>GCMRegistrar.getRegistrationId()</code> first to check if the device is already registered.</p>
<p class="note"><strong>Note:</strong> It is possible that the device was successfully registered to GCM but failed to send the registration ID to your server, in which case you should retry. See <a href="adv.html#reg-state">Advanced Topics</a> for more details on how to handle this scenario.</p>

<h2 id="server-app">Writing the Server-side Application</h2>

<p>To write the server-side application:</p>
<ol>
  <li> Copy the <code>gcm-server.jar</code> file from the SDK's <code>gcm-server/dist</code> directory to your server classpath.</li>
  <li>Create a servlet (or other server-side mechanism) that can be used by the Android application to send the registration ID received by GCM . The application might also need to send other information&mdash;such as the user's email address or username&mdash;so that the server can associate the registration ID with the user owning the device.</li>
  <li>Similarly, create a servlet used to unregister registration IDs.<br>
    </li>
<li>When the server needs to send a message to the registration ID, it can use the <code>com.google.android.gcm.server.Sender</code> helper class from the GCM library. For example:</li>
</ol>

<pre class="prettyprint pretty-java">import com.google.android.gcm.server.*;

Sender sender = new Sender(myApiKey);
Message message = new Message.Builder().build();
MulticastResult result = sender.send(message, devices, 5);</pre>

<p> The snippet above does the following:
<ul>
<li>Creates a <code>Sender</code> object using your project's API key.</li>
<li>Creates a message using a given registration ID (the message builder also has methods to set all message parameters such as the collapse key and payload data).</li>
<li>Sends the message with a maximum of 5 retry attempts (in case the GCM servers are unavailable), and stores the response on result. </li>
</ul>
<p>It's now necessary to parse the result and take the proper action in the following cases:</p>
<ul>
  <li>If the message was created but the result returned a canonical registration ID, it's necessary to replace the current registration ID with the canonical one.</li>
  <li>If the returned error is <code>NotRegistered</code>, it's necessary to remove that registration ID, because the application was uninstalled from the device.</li>
</ul>
<p> Here's a code snippet that handles these 2 conditions:</p>
<pre class="prettyprint pretty-java">
if (result.getMessageId() != null) {
 String canonicalRegId = result.getCanonicalRegistrationId();
 if (canonicalRegId != null) {
   // same device has more than on registration ID: update database
 }
} else {
 String error = result.getErrorCodeName();
 if (error.equals(Constants.ERROR_NOT_REGISTERED)) {
   // application has been removed from device - unregister database
 }
}</pre>