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

对于应用何时可以使用前台服务，Android 14 制定了严格的规则。

此外，在 Android 14 中，我们还引入了一个新 API，用于指定作业必须是用户发起的数据传输作业。此 API 适用于需要由用户发起的持续时间较长的数据传输，例如从远程服务器下载文件。这些类型的任务应使用由用户发起的数据传输作业。

由用户发起的数据传输作业由用户启动。这些作业需要一个通知，会立即启动，并且可能在系统条件允许的情况下长时间运行。您可以同时运行多个由用户发起的数据传输作业。

必须在应用对用户可见的情况下（或在某个允许的条件下）安排由用户发起的作业。满足所有限制条件后，操作系统可以执行由用户发起的作业，具体取决于系统运行状况限制。系统还可以根据提供的估算载荷大小来确定作业的执行时长。

注意：如果您目前针对网络数据传输使用情形使用的是 WorkManager，我们建议您继续使用该库，而不是使用由用户发起的数据传输作业。

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

如需运行用户发起的作业，请执行以下操作：

1. 如果这是您第一次使用 JobScheduler 声明 API，请在清单中声明 JobService 和相关权限。此外，还要为数据传输定义 JobService 的具体子类：

   <service android:name="com.example.app.CustomTransferService"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false">
           ...
   </service>
   

   class CustomTransferService : JobService() {
     ...
   }
   

2. 在清单中声明 RUN_USER_INITIATED_JOBS 权限：

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

3. 构建 JobInfo 对象时，调用新的 setUserInitiated() 方法。我们还建议您在创建作业时通过调用 setEstimatedNetworkBytes() 提供载荷大小估算值：

   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. 在应用可见或在允许的条件列表中，作业应在转移开始前调度：

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

5. 执行作业时，请确保对 JobService 对象调用 setNotification()。该值用于在任务管理器和状态栏通知区域中告知用户作业正在运行：

   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.
     }
   }
   

   注意： 如果您未在短时间内调用 setNotification()，则会导致应用出现 ANR。

6. 定期更新通知，让用户了解作业的状态和进度。如果您在安排作业之前无法确定传输大小，或者需要更新估算的传输大小，请在已知传输大小后使用新的 API updateEstimatedNetworkBytes() 更新传输大小。

7. 执行完成后，调用 jobFinished() 以向系统表明作业已完成，或者应重新调度作业。

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

O usuário pode interromper um job de transferência de dados iniciado pelo usuário que aparece no Gerenciador de tarefas.

Quando o usuário pressiona Stop, o sistema:

• encerra o processo do app imediatamente, incluindo todos os outros jobs ou serviços em execução no primeiro plano;
• não chama onStopJob() para nenhum job em execução;
• impede que os jobs visíveis ao usuário sejam reprogramados.

Por esses motivos, é recomendável fornecer controles na notificação postada para o job para permitir uma interrupção e reprogramação normais.

Em circunstâncias especiais, o botão Stop não aparece ao lado do job no Gerenciador de tarefas, ou então o job não é mostrado no gerenciador de tarefas.

Pelo sistema

Unlike regular jobs, user-initiated data transfer jobs are unaffected by App Standby Buckets quotas. However, the system still stops the job if any of the following conditions occur:

• A developer-defined constraint is no longer met.
• The system determines that the job has run for longer than necessary to complete the data transfer task.
• The system needs to prioritize system health and stop jobs due to increased thermal state.
• The app process is killed due to low device memory.

When the job is stopped by the system (not by the low-memory case), the system calls onStopJob(), and the system retries the job at a time that the system deems to be optimal. Check that your app can persist data transfer state, even if onStopJob() isn't called, and that your app can restore this state when onStartJob() is called again.

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

Os apps só poderão iniciar um job de transferência de dados iniciado pelo usuário se estiverem na janela visível ou se determinadas condições forem atendidas. Para determinar quando um job de transferência de dados iniciado pelo usuário pode ser programado, o sistema aplica a mesma lista de condições que permitem que os apps iniciem uma atividade em segundo plano em casos especiais. Essa lista de condições não é igual ao conjunto de isenções para restrições de serviço em primeiro plano iniciadas em segundo plano.

Confira algumas exceções:

• Se um app puder iniciar atividades em segundo plano, ele também poderá iniciar jobs de transferência de dados iniciados pelo usuário em segundo plano.
• Se um app tiver uma atividade na backstack de uma tarefa na tela Recentes, isso, por si só, não permitirá que um job de transferência de dados iniciado pelo usuário seja executado.

Se o job estiver programado para algum outro momento não listado nas condições permitidas, ele falhará e retornará um código de erro RESULT_FAILURE.

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

为了支持在最佳时间点运行的作业，Android 提供了为每种作业类型分配约束条件的功能。这些约束条件从 Android 13 开始就已经可用。

注意：下表仅比较了因作业类型而异的约束条件。如需了解所有约束条件，请参阅 JobScheduler 开发者页面或工作约束条件。

下表显示了支持给定作业约束条件的不同作业类型，以及 WorkManager 支持的作业约束条件集。您可以使用表格前的搜索栏按作业约束方法的名称过滤表格。

以下是用户发起的数据传输作业允许使用的约束条件：

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

Testes

A lista a seguir mostra algumas etapas para testar os jobs do app manualmente:

• Para encontrar o ID do job, acesse o valor definido após a criação dele.

• Para executar um job imediatamente ou repetir um job interrompido, execute o comando a seguir em uma janela do terminal:

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID
  

• Para simular o fechamento forçado de um job (devido a uma condição de integridade do sistema ou falta de cotas), execute o seguinte comando em uma janela do terminal:

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID