Migrate foreground services to user-initiated data transfer jobs

bookmark_border

Android 14 applies strict rules on when apps are allowed to use foreground services.

Also in Android 14 we are introducing a new API to specify that a job must be a user-initiated data transfer job. This API is helpful for use cases that require longer-duration, user-initiated transferring of data, such as downloading a file from a remote server. These types of tasks should use a user-initiated data transfer job.

User-initiated data transfer jobs are started by the user. These jobs require a notification, start immediately, and may be able to run for an extended period of time as system conditions allow. You can run several user-initiated data transfer jobs concurrently. User initiated jobs must be scheduled while the application is visible to the user (or in one of the allowed conditions. After all constraints are met, user initiated jobs can be executed by the OS, subject to system health restrictions. The system may also use the provided estimated payload size to determine how long the job executes.

Permission for user-initiated data transfer jobs

User-initiated data transfer jobs require a new permission to run: RUN_LONG_JOBS. The system grants this permission automatically. The system throws a SecurityException if you do not declare the permission in your app manifest.

Process for running user-initiated data transfer jobs

To run a user initiated job, do the following:

1. Declare the RUN_LONG_JOBS permission in your manifest:

   <manifest ...>
       <uses-permission android:name="android.permission.RUN_LONG_JOBS" />
       <application ...>
           ...
       </application>
   </manifest>
   

2. Call the new setUserInitiated() and setDataTransfer() methods when building a JobInfo object. It is also recommended that you offer a payload size estimate by calling setEstimatedNetworkBytes() while creating your job:

   val jobInfo = JobInfo.Builder()
           // ...
           .setUserInitiated(true)
           .setDataTransfer(true)
           .setEstimatedNetworkBytes(1024 * 1024 * 1024)
           // ...
           .build()
   

3. Schedule the job while the application is visible, or in the allowed conditions list:

   val jobScheduler: JobScheduler =
           context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
   jobScheduler.schedule(jobInfo)
   

4. When the job is being executed, ensure you call setNotification() on the JobService object. This value is used to make the user aware that the job is running, both in the Task Manager and in the status bar notification area:

   val notification = Notification.Builder(applicationContext, NOTIFICATION_CHANNEL_ID)
           .setContentTitle("My user-initiated data transfer job")
           .setSmallIcon(android.R.mipmap.myicon)
           .setContentText("Job is running")
           .build()
   
   class CustomJobService : JobService() {
     override fun onStartJob(params: JobParameters?): Boolean {
         setNotification(params, notification.id, notification,
                 JobService.JOB_END_NOTIFICATION_POLICY_DETACH)
         // Do the job execution.
     }
   }
   

   Note: If you do not call setNotification() within a short period of time, it will cause an ANR for your app.

5. Periodically update the notification to keep the user informed of the job's status and progress. If you cannot determine the transfer size ahead of scheduling the job, use a new API, updateEstimatedNetworkBytes(), to update the transfer size after it becomes known.

6. When execution is complete, call jobFinished() to signal to the system that the job is complete, or that the job should be rescheduled.

User-initiated data transfer jobs can be stopped from Task Manager

The user can stop a user-initiated data transfer job that appears in the Task Manager.

At the moment that the user presses Stop, the system terminates your app's process immediately, including all other jobs or foreground services running. If the user stops your job using Task Manager or any other system-provided affordance, the job will not be allowed to be rescheduled. Thus, it's recommended to provide controls in the notification posted for the job to allow gracefully stopping and rescheduling the job.

Note that, under special circumstances, the Stop button doesn't appear next to the job in the Task Manager, or the job isn't shown in the Task Manager at all.

Conditions allowed for scheduling user-initiated data transfer jobs

Apps can only start a user-initiated data transfer job if the app is in the visible window, or if the certain conditions are met. To determine when a user-initiated data transfer job can be scheduled, the system applies the same list of conditions that allow apps to start an activity from the background in special cases. Notably, this list of conditions are not the same as the set of exemptions for background-started foreground service restrictions.

The one exception is the Recents screen; if an app has an activity in the back stack of an existing task on the Recents screen, that alone doesn't allow a user-initiated data transfer job to run.

If the job is scheduled at some other time not listed in the allowed conditions list, the job fails and returns a RESULT_FAILURE error code.

Constraints that are allowed for user-initiated data transfer jobs

To support jobs running at optimal points, Android offers the ability to assign constraints to each job type. These constraints are already available as of Android 13.

Note: The following table only compares the constraints that vary between each job type. See JobScheduler developer page or work constraints for all constraints.

The following table shows the different job types that support a given job constraint, as well as the set of job constraints that WorkManager supports. Use the search bar before the table to filter the table by the name of a job constraint method.

These are the constraints allowed with user-initiated data transfer jobs:

• setBackoffCriteria(JobInfo.BACKOFF_POLICY_EXPONENTIAL)
• setClipData()
• setEstimatedNetworkBytes()
• setMinimumNetworkChunkBytes()
• setPersisted()
• setRequiredNetwork()
• setRequiredNetworkType()
• setRequiresBatteryNotLow()
• setRequiresCharging()
• setRequiresStorageNotLow()

Testing

The following list shows some steps on how to test your app's jobs manually:

• To get the job ID, get the value that is defined upon the job being built.

• To run a job immediately, or to retry a stopped job, run the following command in a terminal window:

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAMEJOB_ID
  

• To simulate the system force-stopping a job (due to system health or out-of-quota conditions), run the following command in a terminal window:

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGETEST_JOB_ID