Implementing GCM Network Manager on Android

The GCM Network Manager (GcmNetworkManager) enables client apps to register services that perform network-oriented tasks based on specified criteria such as:

• Schedule one-off vs. periodic tasks. Register one-off or repeating tasks using a simple API call.

• Automatic back-off and failure retry. Return appropriate results (e.g., rescheduled, failed) from the service’s execution logic, and GCM Network Manager handles the necessary back-off and retry.

• Awareness of network activity. The Network Manager's scheduler service leverages many GCM signals and other clients' task execution to determine the optimal time to schedule and execute the task.

• Awareness of device charging state. Certain tasks do not need to be run immediately, and can be executed when the device is charging in order to minimize battery consumption. For such tasks, you can specify that your app should wait to run until the device is charging.

• Persistence of tasks across boot. The GCM Network Manager persists task states across boot and app restarts.

• Ease of implementation/refactoring of existing code. Developers familiar with sync adapters can easily subclass a client service and override one function to add Network Manager to existing apps.

From API level 21 forward, GCM Network Manager uses the framework's JobScheduler.

Edit your application’s manifest

1. Implement GcmTaskService, and add the service to the manifest.

2. Declare SERVICE_PERMISSION to ensure that other apps cannot start your service.

3. Add all applicable intent filters. See details for intent filter support in the GcmTaskService API reference.

Schedule tasks

Schedule tasks based on the client app’s needs. This section provides some examples to get you started. See the GcmNetworkManager API reference for detail on available options.

Get an instance of GcmNetworkManager

In order to schedule and manage tasks from your Activity, you will need an instance of GcmNetworkManager:

Schedule a one-off task when network is connected

Your app can schedule a one-off task to execute only when the user is connected to an unmetered (non-cellular) network, in order to conserve your users' data. The example below shows a task that will execute as soon as the user has an unmetered connection, or at latest one hour after scheduling:

Schedule a periodic task

Your app can schedule a task to occur at regular intervals, with or without constraints on network and charging status. The example below shows a task that will execute at most every 5 seconds:

You can also use the PeriodicTask.Builder#setFlex method to allow the job scheduler to run your task in a flexible time window before the end of the period.

Schedule a persistent task

If you would like your task to be persisted and rescheduled across reboots, call the Task.Builder#setPersisted method when building your task.

Note that in order for task persistence to work, your app must hold the RECEIVE_BOOT_COMPLETED permission.

Run tasks

When the scheduler starts your service, a new thread is created and the system invokes onRunTask(). Implement the logic for your tasks by overriding onRunTask(); its return value specifies exactly what GCM Network Manager should do with this task. See the GCM Network Manager constants RESULT_RESCHEDULE, RESULT_SUCCESS, and RESULT_FAILURE for more information.

Keep in mind that RESULT_SUCCESS and RESULT_FAILURE are not different behaviorally. The distinction between them exists mainly to avoid returning RESULT_SUCCESS if in fact you have determined that your task has failed. Also, it helps in debugging issues locally when you run commands like the following, as you will see the successes/failures for your endpoint listed.

adb shell dumpsys activity service GcmService --endpoints YOUR_ENDPOINT

Client apps should be aware of concurrency issues.

When Google Play Services or the client app is updated, all scheduled tasks are removed. GcmNetworkManager invokes the client app’s onInitializeTasks(). Override this function to reschedule necessary tasks.