The following examples will help you implement Instance ID in an Android
client. Note that these examples use the GCM scope, which is useful only
for demonstration purposes because
[Google Cloud Messaging](https://developers.google.com/cloud-messaging/android/client) has been
retired from use.

## Set Up Google Play Services

To write your client application, use the Google Play services SDK,
as described in [Set up Google Play
Services SDK](http://developer.android.com/google/play-services/setup.html). The Play Services Library includes the Instance ID library.

## Get an Instance ID

The following line of code returns an Instance ID:

    String iid = InstanceID.getInstance(context).getId();

## Generate a token

Generating tokens requires a Project ID generated by the
[Google Developers Console](https://console.developers.google.com/project).

    String authorizedEntity = PROJECT_ID; // Project id from Google Developer Console
    String scope = "GCM"; // e.g. communicating using GCM, but you can use any
                          // URL-safe characters up to a maximum of 1000, or
                          // you can also leave it blank.
    String token = InstanceID.getInstance(context).getToken(authorizedEntity,scope);

## Manage tokens and Instance IDs

Instance ID lets you delete and refresh tokens.

### Delete tokens and Instance IDs

    String authorizedEntity = PROJECT_ID;
    String scope = "GCM";
    InstanceID.getInstance(context).deleteToken(authorizedEntity,scope);

You can also delete the Instance ID itself, including all associated
tokens. The next time you call `getInstance()` you will get a new
Instance ID:

    InstanceID.getInstance(context).deleteInstanceID();
    String newIID = InstanceID.getInstance(context).getId();

> [!NOTE]
> **Note:** If your app used tokens that were deleted by `deleteInstanceID`, your app will need to generate replacement tokens.

### Refresh tokens

The Instance ID service initiates callbacks periodically (for example,
every 6 months), requesting that your app refreshes its tokens. It may also
initiate callbacks when:

- There are security issues; for example, SSL or platform issues.
- Device information is no longer valid; for example, backup and restore.
- The Instance ID service is otherwise affected.

Implement the Instance ID listener service in your app to receive these
callbacks:

    public class MyInstanceIDService extends InstanceIDListenerService {
      public void onTokenRefresh() {
        refreshAllTokens();
      }

      private void refreshAllTokens() {
        // assuming you have defined TokenList as
        // some generalized store for your tokens
        ArrayList<TokenList> tokenList = TokensList.get();
        InstanceID iid = InstanceID.getInstance(this);
        for(tokenItem : tokenList) {
          tokenItem.token =
            iid.getToken(tokenItem.authorizedEntity,tokenItem.scope,tokenItem.options);
          // send this tokenItem.token to your server
        }
      }
    };

You must also configure this service in the Manifest file for the project:

    <service android:name=".MyInstanceIDService" android:exported="false">
      <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID"/>
      </intent-filter>
    </service>