Esta página foi traduzida pela API Cloud Translation.

Transferência de dados iniciada pelo usuário

Se você precisar fazer uma transferência de dados que pode levar muito tempo, crie um job do JobScheduler e identifique-o como um job de transferência de dados iniciada pelo usuário (UIDT). Os jobs de UIDT são destinados a transferências de dados mais longas iniciadas pelo usuário do dispositivo, como o download de um arquivo de um servidor remoto. Os trabalhos de UIDT foram introduzidos no Android 14 (nível 34 da API).

Esses tipos de jobs de transferência de dados são iniciados pelo usuário. Eles exigem uma notificação, são iniciados imediatamente e podem ser executados por um período prolongado, conforme as condições do sistema permitirem. É possível executar vários jobs de transferência de dados iniciados pelo usuário ao mesmo tempo.

Os jobs iniciados pelo usuário precisam ser agendados enquanto o aplicativo está visível para o usuário (ou em uma das condições permitidas). Depois que todas as restrições forem atendidas, os jobs iniciados pelo usuário podem ser executados pelo SO, sujeitos a restrições de integridade do sistema. O sistema também pode usar o tamanho de payload estimado para determinar o período de execução do job.

Programar jobs de transferência de dados iniciados pelo usuário

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

确保您的应用已在其清单中声明 JobService 和关联的权限：

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

此外，还要为数据转移定义 JobService 的具体子类：

Kotlin

class CustomTransferService : JobService() {
  ...
}

Java

class CustomTransferService extends JobService() {

    ....

}

在清单中声明 RUN_USER_INITIATED_JOBS 权限：

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

构建 JobInfo 对象时，调用 setUserInitiated() 方法。（此方法从 Android 14 开始提供。）我们还建议您在创建作业时通过调用 setEstimatedNetworkBytes() 提供载荷大小估算值。

Kotlin

val networkRequestBuilder = NetworkRequest.Builder()
        // Add or remove capabilities based on your requirements.
        // For example, this code specifies that the job won't run
        // unless there's a connection to the internet (not just a local
        // network), and the connection doesn't charge per-byte.
        .addCapability(NET_CAPABILITY_INTERNET)
        .addCapability(NET_CAPABILITY_NOT_METERED)
        .build()

val jobInfo = JobInfo.Builder(jobId,
              ComponentName(mContext, CustomTransferService::class.java))
        // ...
        .setUserInitiated(true)
        .setRequiredNetwork(networkRequestBuilder)
        // Provide your estimate of the network traffic here
        .setEstimatedNetworkBytes(1024 * 1024 * 1024, 1024 * 1024 * 1024)
        // ...
        .build()

Java

NetworkRequest networkRequest = new NetworkRequest.Builder()
    // Add or remove capabilities based on your requirements.
    // For example, this code specifies that the job won't run
    // unless there's a connection to the internet (not just a local
    // network), and the connection doesn't charge per-byte.
    .addCapability(NET_CAPABILITY_INTERNET)
    .addCapability(NET_CAPABILITY_NOT_METERED)
    .build();

JobInfo jobInfo = JobInfo.Builder(jobId,
        new ComponentName(mContext, CustomTransferService.class))
    // ...
    .setUserInitiated(true)
    .setRequiredNetwork(networkRequest)
    // Provide your estimate of the network traffic here
    .setEstimatedNetworkBytes(1024 * 1024 * 1024, 1024 * 1024 * 1024)
    // ...
    .build();

在作业执行期间，对 JobService 对象调用 setNotification()。调用 setNotification() 会在任务管理器和状态栏通知区域中告知用户作业正在运行。

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

Kotlin

class CustomTransferService: JobService() {
    private val scope = CoroutineScope(Dispatchers.IO)

    @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
    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)
        // Execute the work associated with this job asynchronously.
        scope.launch {
            doDownload(params)
        }
        return true
    }

    private suspend fun doDownload(params: JobParameters) {
        // Run the relevant async download task, then call
        // jobFinished once the task is completed.
        jobFinished(params, false)
    }

    // Called when the system stops the job.
    override fun onStopJob(params: JobParameters?): Boolean {
        // Asynchronously record job-related data, such as the
        // stop reason.
        return true // or return false if job should end entirely
    }
}

Java

class CustomTransferService extends JobService{
    @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
    @Override
    public boolean onStartJob(JobParameters params) {
        Notification notification = Notification.Builder(getBaseContext(),
                                        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)
        // Execute the work associated with this job asynchronously.
        new Thread(() -> doDownload(params)).start();
        return true;
    }

    private void doDownload(JobParameters params) {
        // Run the relevant async download task, then call
        // jobFinished once the task is completed.
        jobFinished(params, false);
    }

    // Called when the system stops the job.
    @Override
    public boolean onStopJob(JobParameters params) {
        // Asynchronously record job-related data, such as the
        // stop reason.
        return true; // or return false if job should end entirely
    }
}

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

建议

如需有效运行 UIDT 作业，请执行以下操作：

明确定义网络限制和作业执行限制，以指定作业的执行时间。
在 onStartJob() 中异步执行任务；例如，您可以使用协程来执行此操作。如果您不异步运行任务，工作将在主线程上运行，可能会阻塞主线程，从而导致 ANR。
为避免作业运行时间过长，请在转移完成后（无论成功还是失败）调用 jobFinished()。这样，作业就不会运行过长时间。如需了解作业停止的原因，请实现 onStopJob() 回调方法并调用 JobParameters.getStopReason()。

Compatibilidade com versões anteriores

目前还没有支持 UIDT 作业的 Jetpack 库。因此，我们建议您使用代码来限制变更，以验证您是否在 Android 14 或更高版本上运行。在较低的 Android 版本中，您可以将 WorkManager 的前台服务实现用作回退方法。

以下是检查相应系统版本的代码示例：

Kotlin

fun beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadFGSWorker(context)
    } else {
        scheduleDownloadUIDTJob(context)
    }
}

private fun scheduleDownloadUIDTJob(context: Context) {
    // build jobInfo
    val jobScheduler: JobScheduler =
        context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
    jobScheduler.schedule(jobInfo)
}

private fun scheduleDownloadFGSWorker(context: Context) {
    val myWorkRequest = OneTimeWorkRequest.from(DownloadWorker::class.java)
    WorkManager.getInstance(context).enqueue(myWorkRequest)
}

Java

public void beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadFGSWorker(context);
    } else {
        scheduleDownloadUIDTJob(context);
    }
}

private void scheduleDownloadUIDTJob(Context context) {
    // build jobInfo
    JobScheduler jobScheduler =
            (JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE);
    jobScheduler.schedule(jobInfo);
}

private void scheduleDownloadFGSWorker(Context context) {
    OneTimeWorkRequest myWorkRequest = OneTimeWorkRequest.from(DownloadWorker.class);
    WorkManager.getInstance(context).enqueue(myWorkRequest)
}

Interromper jobs da UIDT

用户和系统都可以停止用户发起的传输作业。

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 o job não é mostrado no Gerenciador de tarefas.

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 por motivos diferentes de pouca memória do dispositivo, o sistema chama onStopJob() e tenta executar o job novamente em um momento que considera ideal. Verifique 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

Os apps só podem 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:

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 ser executado em um momento em que as condições necessárias não forem atendidas, 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

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 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()

Teste

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
```

Veja também

Outros recursos

Para mais informações sobre transferências de dados iniciadas pelo usuário, consulte os seguintes recursos adicionais:

Estudo de caso sobre a integração da UIDT: o Google Maps aumentou a confiabilidade do download em 10% usando a API de transferência de dados iniciada pelo usuário

Transferência de dados iniciada pelo usuário Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Programar jobs de transferência de dados iniciados pelo usuário

Kotlin

Java

Kotlin

Java

Kotlin

Java

建议

Compatibilidade com versões anteriores

Kotlin

Java

Interromper jobs da UIDT

Pelo usuário, no gerenciador de tarefas

Pelo sistema

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

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

Teste

Veja também

Outros recursos

Transferência de dados iniciada pelo usuário