Передача данных, инициируемая пользователем, Передача данных, инициируемая пользователем

Если вам необходимо выполнить передачу данных, которая может занять много времени, вы можете создать задание JobScheduler и определить его как задание передачи данных, инициируемое пользователем (UIDT) . Задания UIDT предназначены для длительной передачи данных, инициируемой пользователем устройства, например, при загрузке файла с удаленного сервера. Задания UIDT были представлены в Android 14 (уровень API 34).

Задания по передаче данных, инициированные пользователем, запускаются пользователем. Эти задания требуют уведомления, запускаются немедленно и могут выполняться в течение длительного периода времени, если позволяют условия системы. Вы можете одновременно запускать несколько заданий по передаче данных, инициированных пользователем.

Задания, инициированные пользователем, необходимо планировать, пока приложение видно пользователю (или в одном из разрешенных условий ). После того, как все ограничения выполнены, задания, инициированные пользователем, могут выполняться операционной системой с учетом ограничений работоспособности системы. Система также может использовать предоставленный расчетный размер полезной нагрузки, чтобы определить, как долго выполняется задание.

Планирование заданий по передаче данных, инициируемых пользователем

Чтобы запустить задание передачи данных, инициированное пользователем, выполните следующие действия:

  1. Убедитесь, что ваше приложение объявило JobService и связанные с ним разрешения в своем манифесте:

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

    Также определите конкретный подкласс JobService для передачи данных:

    Котлин 

    class CustomTransferService : JobService() {
  ...
}

    Ява

    class CustomTransferService extends JobService() {

    ....

}

  2. Объявите разрешение RUN_USER_INITIATED_JOBS в манифесте:

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

  3. Вызовите метод setUserInitiated() при создании объекта JobInfo . (Этот метод доступен, начиная с Android 14.) Мы также рекомендуем вам предложить оценку размера полезных данных, вызвав setEstimatedNetworkBytes() при создании задания.

    Котлин 

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

    Ява

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

  4. Пока задание выполняется, вызовите setNotification() для объекта JobService . Вызов setNotification() сообщает пользователю о том, что задание выполняется, как в диспетчере задач, так и в области уведомлений строки состояния.

    Когда выполнение завершится, вызовите jobFinished() чтобы сообщить системе, что задание завершено или что задание следует перенести.

    Котлин 

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

    Ява

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

  5. Периодически обновляйте уведомление, чтобы держать пользователя в курсе статуса и хода выполнения задания. Если вы не можете определить размер передачи до планирования задания или вам необходимо обновить предполагаемый размер передачи, используйте новый API updateEstimatedNetworkBytes() чтобы обновить размер передачи после того, как он станет известен.

Рекомендации

Для эффективного запуска заданий UIDT выполните следующие действия:

  1. Четко определите сетевые ограничения и ограничения выполнения задания, чтобы указать, когда задание должно выполняться.

  2. Выполните задачу асинхронно в onStartJob() ; например, вы можете сделать это с помощью сопрограммы . Если вы не запустите задачу асинхронно, работа будет выполняться в основном потоке и может заблокировать его, что может вызвать ошибку ANR.

  3. Чтобы избежать выполнения задания дольше, чем необходимо, вызовите jobFinished() после завершения передачи, независимо от того, успешна она или нет. Таким образом, работа не будет выполняться дольше, чем необходимо. Чтобы узнать, почему задание было остановлено, реализуйте метод обратного вызова onStopJob() и вызовите JobParameters.getStopReason() .

,

Чтобы запустить задание передачи данных, инициированное пользователем, выполните следующие действия:

  1. Убедитесь, что ваше приложение объявило JobService и связанные с ним разрешения в своем манифесте:

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

    Также определите конкретный подкласс JobService для передачи данных:

    Котлин 

    class CustomTransferService : JobService() {
  ...
}

    Ява

    class CustomTransferService extends JobService() {

    ....

}

  2. Объявите разрешение RUN_USER_INITIATED_JOBS в манифесте:

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

  3. Вызовите метод setUserInitiated() при создании объекта JobInfo . (Этот метод доступен, начиная с Android 14.) Мы также рекомендуем вам предложить оценку размера полезных данных, вызвав setEstimatedNetworkBytes() при создании задания.

    Котлин 

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

    Ява

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

  4. Пока задание выполняется, вызовите setNotification() для объекта JobService . Вызов setNotification() сообщает пользователю о том, что задание выполняется, как в диспетчере задач, так и в области уведомлений строки состояния.

    Когда выполнение завершится, вызовите jobFinished() чтобы сообщить системе, что задание завершено или что задание следует перенести.

    Котлин 

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

    Ява

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

  5. Периодически обновляйте уведомление, чтобы держать пользователя в курсе статуса и хода выполнения задания. Если вы не можете определить размер передачи до планирования задания или вам необходимо обновить предполагаемый размер передачи, используйте новый API updateEstimatedNetworkBytes() чтобы обновить размер передачи после того, как он станет известен.

Рекомендации

Для эффективного запуска заданий UIDT выполните следующие действия:

  1. Четко определите сетевые ограничения и ограничения выполнения задания, чтобы указать, когда задание должно выполняться.

  2. Выполните задачу асинхронно в onStartJob() ; например, вы можете сделать это с помощью сопрограммы . Если вы не запустите задачу асинхронно, работа будет выполняться в основном потоке и может заблокировать его, что может вызвать ошибку ANR.

  3. Чтобы избежать выполнения задания дольше, чем необходимо, вызовите jobFinished() после завершения передачи, независимо от того, успешна она или нет. Таким образом, работа не будет выполняться дольше, чем необходимо. Чтобы узнать, почему задание было остановлено, реализуйте метод обратного вызова onStopJob() и вызовите JobParameters.getStopReason() .

Обратная совместимость

В настоящее время не существует библиотеки Jetpack, поддерживающей задания UIDT. По этой причине мы рекомендуем вам подтвердить изменение с помощью кода, который подтверждает, что вы используете Android 14 или более поздней версии. В более ранних версиях Android вы можете использовать реализацию службы переднего плана WorkManager в качестве запасного варианта.

Вот пример кода, который проверяет соответствующую версию системы:

Котлин 

fun beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadUIDTJob(context)
    } else {
        scheduleDownloadFGSWorker(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)
}

Ява

public void beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadUIDTJob(context);
    } else {
        scheduleDownloadFGSWorker(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() .

Условия, разрешенные для планирования заданий по передаче данных, инициируемых пользователем

Приложения могут запускать инициированное пользователем задание по передаче данных только в том случае, если приложение находится в видимом окне или выполняются определенные условия:

  • Если приложение может запускать действия в фоновом режиме , оно также может запускать в фоновом режиме инициируемые пользователем задания по передаче данных.
  • Если в приложении есть действие в стеке существующей задачи на экране «Последние» , это само по себе не позволяет выполнить задание по передаче данных, инициированное пользователем.

Если выполнение задания запланировано на момент, когда необходимые условия не выполняются, задание завершается с ошибкой и возвращается код ошибки RESULT_FAILURE .

Ограничения, разрешенные для заданий передачи данных, инициируемых пользователем

Для поддержки заданий, выполняемых в оптимальных точках, Android предлагает возможность назначать ограничения для каждого типа заданий. Эти ограничения доступны начиная с Android 13.

Примечание . В следующей таблице сравниваются только ограничения, которые различаются для каждого типа задания. См. страницу разработчика JobScheduler или рабочие ограничения для всех ограничений.

В следующей таблице показаны различные типы заданий, которые поддерживают данное ограничение задания, а также набор ограничений задания, которые поддерживает WorkManager. Используйте панель поиска перед таблицей, чтобы отфильтровать ее по имени метода ограничения задания.

Ниже приведены ограничения, допускаемые при заданиях передачи данных, инициируемых пользователем:

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

Тестирование

В следующем списке показаны некоторые шаги по тестированию заданий вашего приложения вручную:

  • Чтобы получить идентификатор задания, получите значение, определенное при создании задания.

  • Чтобы немедленно запустить задание или повторить остановленное задание, выполните следующую команду в окне терминала:

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

  • Чтобы смоделировать принудительную остановку задания системой (из-за состояния системы или превышения квоты), выполните следующую команду в окне терминала:

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

См. также

Дополнительные ресурсы

Дополнительные сведения о передаче данных, инициируемой пользователем, см. в следующих дополнительных ресурсах: