将前台服务迁移到用户发起的数据传输作业

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

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

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

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

用户发起的数据传输作业的权限

由用户发起的数据传输作业需要具备以下新权限才能运行:RUN_USER_INITIATED_JOBS。系统会自动授予此权限。如果您未在应用清单中声明此权限,系统会抛出 SecurityException

安排用户发起的数据传输作业的流程

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

  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.
      }
    }
    
  6. 定期更新通知,让用户了解作业的状态和进度。如果在安排作业之前无法确定传输大小,或者需要更新估算的传输大小,请在知道传输大小后使用新的 API updateEstimatedNetworkBytes() 更新传输大小。

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

可以停止用户发起的数据传输作业

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

由用户从任务管理器提供

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

在用户按 Stop 时,系统会执行以下操作:

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

因此,建议在发布的作业通知中提供控件,以便顺利停止和重新调度作业。

请注意,在特殊情况下,Stop 按钮不会显示在任务管理器中的作业旁边,或者该作业根本不会显示在任务管理器中。

由系统提供

与常规作业不同,用户发起的数据传输作业不受应用待机模式存储分区配额的影响。但是,如果出现以下任一情况,系统仍会停止作业:

  • 不再满足开发者定义的约束条件。
  • 系统确定该作业的运行时间超出了完成数据传输任务所需的时间。
  • 系统需要优先考虑系统运行状况,并因发热程度上升而停止作业。
  • 应用进程因设备内存不足而被终止。

系统停止作业(并非因为内存不足)时,系统会调用 onStopJob(),系统会在系统认为最佳的时间重试作业。检查您的应用是否可以保留数据传输状态(即使未调用 onStopJob()),并且您的应用可以在再次调用 onStartJob() 时恢复此状态。

允许安排用户发起的数据传输作业的条件

只有当应用处于可见窗口中或满足特定条件时,应用才能启动用户发起的数据传输作业。为确定何时可以安排用户发起的数据传输作业,系统会采用允许应用在特殊情况下从后台启动 activity 的一组相同条件。值得注意的是,这组条件与后台启动的前台服务限制的豁免集不同。

上述说明的例外情况包括:

  • 如果应用可以从后台启动 activity,则也可以从后台启动用户发起的数据传输作业。
  • 如果应用在最近用过屏幕上现有任务的返回堆栈中有 activity,单靠这一点并不允许运行用户发起的数据传输作业。

如果作业安排在允许的条件列表中未列出的其他时间,则作业将失败并返回 RESULT_FAILURE 错误代码。

适用于用户发起的数据传输作业的约束条件

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

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

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

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

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

测试

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

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

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

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID