Merge "Doc update: redo of new API Console steps." into klp-docs

will get a <code>NotRegistered</code> error. See <a href="#unreg">

How Unregistration Works</a> for more information.</p>

<p>Although is not possible to track the status of each individual message, the

Google APIs Console stats are broken down by messages sent to device, messages

Google Cloud Console stats are broken down by messages sent to device, messages

collapsed, and messages waiting for delivery.</p>

<h2 id="throttling">Throttling</h2>

<p>GCM will store up to 100 non-collapsible messages. After that, all messages

are discarded from GCM, and a new message is created that tells the client how

far behind it is. The message is delivered through a regular

<code>com.google.android.c2dm.intent.RECEIVE</code> intent, with the following

extras:</p>

<ul>

  <li> <code>message_type</code>&mdash;The value is always the string

&quot;deleted_messages&quot;.</li>

  <li><code>total_deleted</code>&mdash;The value  is a string with the number of

deleted messages.</li>

</ul>

<code>com.google.android.c2dm.intent.RECEIVE</code> intent with the

extra <code>message_type</code>, for which the value is always the string

&quot;deleted_messages&quot;.</p>

<p>The application should respond by syncing with the server to recover the

discarded messages. </p>

        }

    }.execute(null, null, null);

    ...

}</pre>

<p>Once you've received your registration ID, send it to your server:</p>

<pre>

/**

 * Sends the registration ID to your server over HTTP, so it can use GCM/HTTP

 * or CCS to send messages to your app. Not needed for this demo since the

 */

private void sendRegistrationIdToBackend() {

    // Your implementation here.

    }

}</pre>

<p>After registering, the app calls {@code storeRegistrationId()} to store the

<p class="note"><strong>Note:</strong> Stats on the Google API Console are not

enabled for GCM. You must use the <a href="http://play.google.com/apps/publish">Developer Console</a>.</p>

    <th colspan="2">Credentials</th>

  </tr>

  <tr>

    <td><strong>Sender ID</strong></td>

    <td id="senderid"><strong>Sender ID</strong></td>

    <td>A project number you acquire from the API console, as described in

<a href="gs.html#create-proj">Getting Started</a>. The sender

ID is used in the <a href="#register">registration process</a> to identify a

account if the device is running a version lower than Android 4.0.4.</td>

  </tr>

  <tr>

    <td><strong>Sender Auth Token</strong></td>

    <td id="apikey"><strong>Sender Auth Token</strong></td>

    <td>An API key that is saved on the 3rd-party application

server that gives the application server authorized access to Google services.

The API key is included in the header of POST requests  that send messages.</td>

<h2>See Also</h2>

<ol class="toc">

<li><a href="https://code.google.com/apis/console">Google APIs Console page</a></li>

<li><a href="https://cloud.google.com/console">Google Cloud Console</a></li>

<li><a href="https://developers.google.com/console/help/new/">Google Cloud Console Help</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>

<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html">

{@code GoogleCloudMessaging}</a> methods.</p>

<h2 id="create-proj">Creating a Google API project</h2>

<p>To create a Google API project:</p>

<ol>

  <li>Open the <a href="https://code.google.com/apis/console">Google APIs Console page</a>.

  <li>Open the <a href="https://cloud.google.com/console">Google Cloud Console</a>.

  </li>

  <li>If you haven't created an API project yet, this page will prompt you to do so:

  <p><img src="{@docRoot}images/gcm/gcm-create-api-proj.png" class="screenshot" /></p>

<p class="note"><strong>Note:</strong> If you already have existing projects,

the first page you see will be the <strong>Dashboard</strong> page. From there

you can create a new project by opening the project drop-down menu (upper left corner)

and choosing <strong>Other projects > Create</strong>.</p></li>

  <li> Click <strong>Create project</strong>.

    Your browser URL will change to something like:</li>

  <li>If you haven't created an API project yet, click <strong>Create Project</strong>.</li>

 <li>Supply a project name and click <strong>Create</strong>.

<pre> https://code.google.com/apis/console/#project:<strong>4815162342</strong></pre>

<p>Once the project has been created, a page appears that displays your project ID and

project number. For example, <strong>Project Number: 670330094152</strong>.</p></li>

  <li> Take note of the value after <code>#project:</code> (4815162342 in this

example). This is your project number, and it will be used later on as the GCM sender ID.</li>

  <li>Copy down your project number. You will use it later on as the

  <a href="{@docRoot}google/gcm/gcm.html#senderid">GCM sender ID</a>.</li>

</ol>

<h2 id="gcm-service">Enabling the GCM Service</h2>

<p>To enable the GCM service:</p>

<ol>

  <li> In the main Google APIs Console page, select <strong>Services</strong>.</li>

  <li>Turn the <strong>Google Cloud Messaging</strong> toggle to ON.</li>

  <li>In the Terms of Service page, accept the terms.

  </li>

  <li>In the sidebar on the left, select <strong>APIs &amp; auth</strong>. </li>

  <li>In the displayed list of APIs, turn the <strong>Google Cloud Messaging for Android

  </strong> toggle to ON.</li>

</ol>

<h2 id="access-key">Obtaining an API Key</h2>

<p>To obtain an API  key:</p>

<ol>

  <li> In the main Google APIs Console page, select <strong>API Access</strong>.

You will see a screen that resembles the following:</li>

<img src="{@docRoot}images/gcm/gcm-api-access.png" style="width:400px;padding:4px;">

  <li>Click  <strong>Create new Server key</strong>. Either a server key or a

browser key should work. The advantage to using a server key is that it allows

you to whitelist IP addresses. The following screen appears:</li>

 <li>In the sidebar on the left, select <strong>APIs &amp; auth > Registered apps</strong>.</li>

<li>Click <strong>Register app</strong>. </li>

<img src="{@docRoot}images/gcm/gcm-config-server-key.png" style="width:400px;padding:4px;">

<li>In the <strong>Name</strong> field, type your app's name.</li>

<li>Click <strong>Android > Accessing APIs directly from Android</strong>.</li>

<li>Under <strong>Android identification</strong>, type the package name for your app.</li>

<li>Enter an SHA1 fingerprint. To get this value, follow the instructions in the

<a href="http://developers.google.com/console/help/new/#installedapplications">console

help</a>.</li>

<li>Click <strong>Register</strong>.</li>

<li>In the new page, open the <strong>Android Key</strong> section and copy the

<a href="{@docRoot}google/gcm/gcm.html#apikey">API key</a>.

You will need the API key later on to perform authentication in your application server.</li>

  <li>Click <strong>Create</strong>:</li>

<img src="{@docRoot}images/gcm/gcm-api-key.png" style="width:400px;padding:4px;">

</ol>

<p> Take note of the <strong>API key</strong> value (<code>YourKeyWillBeShownHere</code>)

in this example, as it will be used later on.</p>

<p class="note"><strong>Note:</strong> If you need to rotate the key, click

<strong>Generate new key</strong>. 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 <strong>Delete key</strong>.</p>

the "recycle key" icon. A new key  will be created. If you think the key has been compromised

and you want to delete it immediately, you can accomplish this by deleting the app from

the console. Then create a new entry for the app with the same SHA1 and package name.</p>

</ol>

<h2 id="next">Next Steps</h2>

on a device. See <a href="client.html">Implementing GCM Client</a> for more information.</li>

</ol>

  <li>When the device is online, Google sends the message to the device.</li>

  <li>On the device, the system broadcasts the message to the specified Android

application via Intent broadcast with proper permissions, so that only the targeted

ndroid application gets the message. This wakes the Android application up.

Android application gets the message. This wakes the Android application up.

The Android application does not need to be running beforehand to receive the message.</li>

  <li>The Android application processes the message. </li>

</ol>

<p>Required. When your app server sends a message in GCM, it must specify a target.</p>

<p>For HTTP you must specify the target as one of:</p>

<ul>

<li><code>registration_ids</code>: For sending to 1 more more devices (up to 1000).

<li><code>registration_ids</code>: For sending to 1 or more devices (up to 1000).

When you send a message to multiple registration IDs, that is called a multicast message.</li>

<li><code>notification_key</code>: For sending to multiple devices owned by a single user.</li>

</ul>