com.google.android.gcm

Class GCMRegistrar

java.lang.Object

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

Fields

Modifier and Type	Field and Description
static long	DEFAULT_ON_SERVER_LIFESPAN_MS Default lifespan (7 days) of the isRegisteredOnServer(Context) flag until it is considered expired.

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkDevice(android.content.Context context) Checks if the device has the proper dependencies installed.
static void	checkManifest(android.content.Context context) Checks that the application manifest is properly configured.
static long	getRegisterOnServerLifespan(android.content.Context context) Gets how long (in milliseconds) the isRegistered(Context) property is valid.
static java.lang.String	getRegistrationId(android.content.Context context) Gets the current registration id for application on GCM service.
static boolean	isRegistered(android.content.Context context) Checks whether the application was successfully registered on GCM service.
static boolean	isRegisteredOnServer(android.content.Context context) Checks whether the device was successfully registered in the server side, as set by setRegisteredOnServer(Context, boolean).
static void	onDestroy(android.content.Context context) Clear internal resources.
static void	register(android.content.Context context, java.lang.String... senderIds) Initiate messaging registration for the current application.
static void	setRegisteredOnServer(android.content.Context context, boolean flag) Sets whether the device was successfully registered in the server side.
static void	setRegisterOnServerLifespan(android.content.Context context, long lifespan) Sets how long (in milliseconds) the isRegistered(Context) flag is valid.
static void	unregister(android.content.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(android.content.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(android.content.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 permission.
4. The BroadcastReceiver(s) handles the 2 GCM intents ( and ).

...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(android.content.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(android.content.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(android.content.Context context)

Clear internal resources.

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

getRegistrationId

public static java.lang.String getRegistrationId(android.content.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(android.content.Context context)

Checks whether the application was successfully registered on GCM service.

setRegisteredOnServer

public static void setRegisteredOnServer(android.content.Context context,
                         boolean flag)

Sets whether the device was successfully registered in the server side.

isRegisteredOnServer

public static boolean isRegisteredOnServer(android.content.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(android.content.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(android.content.Context context,
                               long lifespan)

Sets how long (in milliseconds) the isRegistered(Context) flag is valid.