The Android 15 Beta is now available. Try it out today and let us know what you think!

Эта страница переведена с помощью Cloud Translation API.

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

В Android 14 применяются строгие правила относительно того, когда приложениям разрешено использовать службы переднего плана.

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

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

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

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

Для выполнения заданий передачи данных, инициируемых пользователем, требуется новое разрешение: RUN_USER_INITIATED_JOBS . Система предоставляет это разрешение автоматически. Система выдает SecurityException , если вы не укажете разрешение в манифесте приложения.

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

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

Если вы впервые объявляете API с помощью JobScheduler, объявите JobService и связанные с ним разрешения в своем манифесте. Также определите конкретный подкласс JobService для передачи данных:
```
<service android:name="com.example.app.CustomTransferService"
        android:permission="android.permission.BIND_JOB_SERVICE"
        android:exported="false">
        ...
</service>
```
```
class CustomTransferService : JobService() {
  ...
}
```

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

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

Вызовите новый метод setUserInitiated() при создании объекта JobInfo . Также рекомендуется предоставить оценку размера полезной нагрузки, вызвав 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()

Запланируйте задание до начала передачи, пока приложение видно или находится в списке разрешенных условий :
```
val jobScheduler: JobScheduler =
    context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
jobScheduler.schedule(jobInfo)
```
Когда задание выполняется, убедитесь, что вы вызываете setNotification() для объекта JobService . Это значение используется для информирования пользователя о том, что задание выполняется, как в диспетчере задач, так и в области уведомлений строки состояния:
```
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 для вашего приложения.
Периодически обновляйте уведомление, чтобы держать пользователя в курсе статуса и хода выполнения задания. Если вы не можете определить размер передачи до планирования задания или вам необходимо обновить предполагаемый размер передачи, используйте новый API updateEstimatedNetworkBytes() чтобы обновить размер передачи после того, как он станет известен.
Когда выполнение завершится, вызовите jobFinished() , чтобы сообщить системе, что задание завершено или что задание следует перенести.

Задания по передаче данных, инициированные пользователем, можно остановить.

И пользователь, и система могут остановить инициированные пользователем задания по передаче.

Пользователь, из диспетчера задач

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

В тот момент, когда пользователь нажимает «Стоп» , система делает следующее:

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

По этим причинам рекомендуется предоставить элементы управления в уведомлении, публикуемом для задания, чтобы можно было корректно останавливать и перепланировать задание.

Обратите внимание, что в особых случаях кнопка «Стоп» не отображается рядом с заданием в диспетчере задач или задание вообще не отображается в диспетчере задач.

По системе

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.

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

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

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

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

Если задание запланировано на другое время, не указанное в списке разрешенных условий, задание завершается с ошибкой и возвращается код ошибки 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
```