Migrar serviços em primeiro plano para jobs de transferência de dados iniciados pelo usuário

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.

Permissão para jobs de transferência de dados iniciados pelo usuário

Os jobs de transferência de dados iniciados pelo usuário exigem uma nova permissão para serem executados: RUN_USER_INITIATED_JOBS. O sistema concede essa permissão automaticamente. Ele gera uma SecurityException quando você não declara a permissão no manifesto do app.

Processo para programar jobs de transferência de dados iniciados pelo usuário

To run a user initiated job, do the following:

  1. If this is your first time declaring an API with JobScheduler, declare the JobService and associated permissions in your manifest. Also, define a concrete subclass of JobService for your data transfer:

    <service android:name="com.example.app.CustomTransferService"
            android:permission="android.permission.BIND_JOB_SERVICE"
            android:exported="false">
            ...
    </service>
    
    class CustomTransferService : JobService() {
      ...
    }
    
  2. Declare the RUN_USER_INITIATED_JOBS permission in your manifest:

    <manifest ...>
        <uses-permission android:name="android.permission.RUN_USER_INITIATED_JOBS" />
        <application ...>
            ...
        </application>
    </manifest>
    
  3. Call the new setUserInitiated() method when building a JobInfo object. It is also recommended that you offer a payload size estimate by calling setEstimatedNetworkBytes() while creating your job:

    val networkRequestBuilder = NetworkRequest.Builder()
            .addCapability(NET_CAPABILITY_INTERNET)
            .addCapability(NET_CAPABILITY_NOT_METERED)
            // Add or remove capabilities based on your requirements
            .build()
    
    val jobInfo = JobInfo.Builder()
            // ...
            .setUserInitiated(true)
            .setRequiredNetwork(networkRequestBuilder.build())
            .setEstimatedNetworkBytes(1024 * 1024 * 1024)
            // ...
            .build()
    
  4. Schedule the job before the transfer starts, 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)
    
  5. 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:

    class CustomTransferService : JobService() {
      override fun onStartJob(params: JobParameters?): Boolean {
          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()
    
          setNotification(params, notification.id, notification,
                  JobService.JOB_END_NOTIFICATION_POLICY_DETACH)
          // Do the job execution.
      }
    }
    
  6. 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, or need to update the estimated transfer size, use the new API, updateEstimatedNetworkBytes() to update the transfer size after it becomes known.

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

Os jobs de transferência de dados iniciados pelo usuário podem ser interrompidos

O usuário e o sistema podem interromper jobs de transferência iniciados pelo usuário.

Pelo usuário, no gerenciador de tarefas

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 does the following:

  • Terminates your app's process immediately, including all other jobs or foreground services running.
  • Doesn't call onStopJob() for any running jobs.
  • Prevets user-visible jobs from being rescheduled.

For these reasons, 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.

Pelo sistema

Diferente dos jobs normais, os jobs de transferência de dados iniciados pelo usuário não são afetados pelas cotas de buckets de apps em espera. No entanto, o sistema ainda interromperá o job se alguma das condições a seguir ocorrer:

  • Uma restrição definida pelo desenvolvedor não é mais atendida.
  • O sistema determina que o job foi executado por mais tempo que o necessário para concluir a tarefa de transferência de dados.
  • O sistema precisa priorizar a integridade e interromper os jobs devido ao aumento do estado térmico.
  • O processo do app é encerrado devido à pouca memória do dispositivo.

Quando o job é interrompido pelo sistema (não pelo caso de pouca memória), o sistema chama onStopJob() e tenta executar o job novamente em um momento que considera ideal. Confira se o app pode manter o estado de transferência de dados, mesmo que onStopJob() não seja chamado, e se ele pode restaurar esse estado quando onStartJob() é chamado novamente.

Condições permitidas para programar jobs de transferência de dados iniciados pelo usuário

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 exceptions to the previous statement are the following:

  • If an app can launch activities from the background, they can also launch user-initiated data transfer jobs from the background.
  • 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.

Restrições permitidas para jobs de transferência de dados iniciados pelo usuário

Para oferecer suporte a jobs em execução nos pontos ideais, no Android é possível atribuir restrições a cada tipo de job. Essas restrições já estão disponíveis desde o Android 13.

Observação: a tabela a seguir compara somente as restrições que variam entre cada tipo de job. Consulte a Página do desenvolvedor do JobScheduler ou as restrições de trabalho para conferir todas as restrições.

A tabela a seguir mostra os diferentes tipos de job que aceitam determinada restrição, bem como o conjunto de restrições de jobs com suporte ao WorkManager. Use a barra de pesquisa antes da tabela para filtrá-la pelo nome de um método de restrição de job.

Estas são as restrições permitidas com jobs de transferência de dados iniciados pelo usuário:

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

Testes

下面列出了有关如何手动测试应用作业的一些步骤:

  • 如需获取作业 ID,请获取在构建作业时定义的值。
  • 如需立即运行作业或重试已停止的作业,请在终端窗口中运行以下命令:

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID
    
  • 如需模拟系统强行停止作业(由于系统运行状况或超出配额条件),请在终端窗口中运行以下命令:

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID