com.google.android.gcm
Class GCMRegistrar

java.lang.Object
  extended by com.google.android.gcm.GCMRegistrar

public final class GCMRegistrar
extends java.lang.Object

Utilities for device registration.

Note: this class uses a private SharedPreferences object to keep track of the registration token.


Field Summary
static long DEFAULT_ON_SERVER_LIFESPAN_MS
          Default lifespan (7 days) of the isRegisteredOnServer(Context) flag until it is considered expired.
 
Method Summary
static void checkDevice(Context context)
          Checks if the device has the proper dependencies installed.
static void checkManifest(Context context)
          Checks that the application manifest is properly configured.
static long getRegisterOnServerLifespan(Context context)
          Gets how long (in milliseconds) the isRegistered(Context) property is valid.
static java.lang.String getRegistrationId(Context context)
          Gets the current registration id for application on GCM service.
static boolean isRegistered(Context context)
          Checks whether the application was successfully registered on GCM service.
static boolean isRegisteredOnServer(Context context)
          Checks whether the device was successfully registered in the server side, as set by setRegisteredOnServer(Context, boolean).
static void onDestroy(Context context)
          Clear internal resources.
static void register(Context context, java.lang.String... senderIds)
          Initiate messaging registration for the current application.
static void setRegisteredOnServer(Context context, boolean flag)
          Sets whether the device was successfully registered in the server side.
static void setRegisterOnServerLifespan(Context context, long lifespan)
          Sets how long (in milliseconds) the isRegistered(Context) flag is valid.
static void unregister(Context context)
          Unregister the application.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_ON_SERVER_LIFESPAN_MS

public static final long DEFAULT_ON_SERVER_LIFESPAN_MS
Default lifespan (7 days) of the isRegisteredOnServer(Context) flag until it is considered expired.

See Also:
Constant Field Values
Method Detail

checkDevice

public static void checkDevice(Context context)
Checks if the device has the proper dependencies installed.

This method should be called when the application starts to verify that the device supports GCM.

Parameters:
context - application context.
Throws:
java.lang.UnsupportedOperationException - if the device does not support GCM.

checkManifest

public static void checkManifest(Context context)
Checks that the application manifest is properly configured.

A proper configuration means:

  1. It creates a custom permission called PACKAGE_NAME.permission.C2D_MESSAGE.
  2. It defines at least one BroadcastReceiver with category PACKAGE_NAME.
  3. The BroadcastReceiver(s) uses the "com.google.android.c2dm.permission.SEND" permission.
  4. The BroadcastReceiver(s) handles the 2 GCM intents ("com.google.android.c2dm.intent.RECEIVE" and "com.google.android.c2dm.intent.REGISTRATION").
...where PACKAGE_NAME is the application package.

This method should be used during development time to verify that the manifest is properly set up, but it doesn't need to be called once the application is deployed to the users' devices.

Parameters:
context - application context.
Throws:
java.lang.IllegalStateException - if any of the conditions above is not met.

register

public static void register(Context context,
                            java.lang.String... senderIds)
Initiate messaging registration for the current application.

The result will be returned as an GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK intent with either a GCMConstants.EXTRA_REGISTRATION_ID or GCMConstants.EXTRA_ERROR.

Parameters:
context - application context.
senderIds - Google Project ID of the accounts authorized to send messages to this application.
Throws:
java.lang.IllegalStateException - if device does not have all GCM dependencies installed.

unregister

public static void unregister(Context context)
Unregister the application.

The result will be returned as an GCMConstants.INTENT_FROM_GCM_REGISTRATION_CALLBACK intent with an GCMConstants.EXTRA_UNREGISTERED extra.


onDestroy

public static void onDestroy(Context context)
Clear internal resources.

This method should be called by the main activity's onDestroy() method.


getRegistrationId

public static java.lang.String getRegistrationId(Context context)
Gets the current registration id for application on GCM service.

If result is empty, the registration has failed.

Returns:
registration id, or empty string if the registration is not complete.

isRegistered

public static boolean isRegistered(Context context)
Checks whether the application was successfully registered on GCM service.


setRegisteredOnServer

public static void setRegisteredOnServer(Context context,
                                         boolean flag)
Sets whether the device was successfully registered in the server side.


isRegisteredOnServer

public static boolean isRegisteredOnServer(Context context)
Checks whether the device was successfully registered in the server side, as set by setRegisteredOnServer(Context, boolean).

To avoid the scenario where the device sends the registration to the server but the server loses it, this flag has an expiration date, which is DEFAULT_ON_SERVER_LIFESPAN_MS by default (but can be changed by setRegisterOnServerLifespan(Context, long)).


getRegisterOnServerLifespan

public static long getRegisterOnServerLifespan(Context context)
Gets how long (in milliseconds) the isRegistered(Context) property is valid.

Returns:
value set by setRegisteredOnServer(Context, boolean) or DEFAULT_ON_SERVER_LIFESPAN_MS if not set.

setRegisterOnServerLifespan

public static void setRegisterOnServerLifespan(Context context,
                                               long lifespan)
Sets how long (in milliseconds) the isRegistered(Context) flag is valid.