用户发起的数据传输

如果您需要执行可能耗时较长的数据传输，可以创建 JobScheduler 作业，并将其标识为“用户发起的数据传输 (UIDT)”作业。UIDT 作业适用于由设备用户发起、持续时间较长的数据传输，例如从远程服务器下载文件。UIDT 作业随 Android 14 (API 级别 34) 引入。

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

用户发起的作业必须在应用对用户可见时（或在允许的条件之一）进行调度。满足所有约束后，用户发起的作业可由操作系统执行，但须遵守系统健康状况限制。系统还可能会使用提供的预估负载大小来确定作业的执行时间。

调度用户发起的数据传输作业

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

确保您的应用已在其清单中声明 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)
        // ...
        .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, DownloadTransferService.class))
    // ...
    .setUserInitiated(true)
    .setRequiredNetwork(networkRequest)
    // Provide your estimate of the network traffic here
    .setEstimatedNetworkBytes(1024 * 1024 * 1024)
    // ...
    .build();

作业执行期间，在 JobService 对象上调用 setNotification()。调用 setNotification() 会让用户知道作业正在运行，无论是在任务管理器中还是在状态栏通知区域。

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

Kotlin

class DownloadTransferService: 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 DownloadTransferService 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()。

向后兼容性

目前没有支持 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)
}

停止 UIDT 作业

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

由用户通过任务管理器停止

用户可以停止显示在任务管理器中的用户发起的数据传输作业。

用户按下停止按钮时，系统会执行以下操作

立即终止您的应用进程，包括所有其他正在运行的作业或前台服务。
不对任何正在运行的作业调用 onStopJob()。
阻止用户可见的作业被重新调度。

因此，建议在为作业发布的通知中提供控件，以便正常停止和重新调度作业。

请注意，在特殊情况下，停止按钮可能不会显示在任务管理器中作业旁边，或者作业根本不会显示在任务管理器中。

由系统停止

与常规作业不同，用户发起的数据传输作业不受应用待机优化分桶配额的影响。但是，如果发生以下任何情况，系统仍会停止该作业

开发者定义的约束不再满足。
系统确定作业运行时间超过完成数据传输任务的必要时长。
系统需要优先考虑系统健康状况，并因热状态升高而停止作业。
应用进程因设备内存不足而被终止。

当系统出于非设备内存不足的原因停止作业时，系统会调用 onStopJob()，并且系统会在其认为最佳的时间重试作业。请确保您的应用即使在未调用 onStopJob() 的情况下也能持久保留数据传输状态，并且您的应用在再次调用 onStartJob() 时可以恢复此状态。

允许调度用户发起的数据传输作业的条件

应用只能在应用位于可见窗口中或满足某些条件时才能启动用户发起的数据传输作业

如果应用可以从后台启动 activity，它也可以从后台启动用户发起的数据传输作业。
如果应用在“最近”屏幕上的现有任务的返回堆栈中包含 activity，仅凭这一点并不能允许用户发起的数据传输作业运行。

如果作业计划在不满足必要条件的时间运行，则作业会失败并返回 RESULT_FAILURE 错误代码。