The GCM Network Manager (
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.
Edit your application’s manifest
GcmTaskService, and add the service to the manifest.
SERVICE_PERMISSIONto ensure that other apps cannot start your service.
Add all applicable intent filters. See details for intent filter support in the
<service android:name=".MyTaskService" android:exported="true" android:permission="com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE"> <intent-filter> <action android:name="com.google.android.gms.gcm.ACTION_TASK_READY" /> </intent-filter> </service>
Schedule tasks based on the client app’s needs. This section provides some examples to get you started.
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
mGcmNetworkManager = GcmNetworkManager.getInstance(this);
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:
OneoffTask task = new OneoffTask.Builder() .setService(MyTaskService.class) .setTag(TASK_TAG_WIFI) .setExecutionWindow(0L, 3600L) .setRequiredNetwork(Task.NETWORK_STATE_UNMETERED) .build(); mGcmNetworkManager.schedule(task);
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 30 seconds:
PeriodicTask task = new PeriodicTask.Builder() .setService(MyTaskService.class) .setTag(TASK_TAG_PERIODIC) .setPeriod(30L) .build(); mGcmNetworkManager.schedule(task);
You can also use the
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
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_FAILURE for more information.
Keep in mind that
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.