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

Halaman ini diterjemahkan oleh Cloud Translation API.

Memigrasikan layanan latar depan ke tugas transfer data yang dimulai pengguna

Android 14 menerapkan aturan ketat tentang kapan aplikasi diizinkan untuk menggunakan layanan latar depan.

Di Android 14, kami juga memperkenalkan API baru untuk menentukan bahwa tugas harus berupa tugas transfer data yang dimulai pengguna. API ini berguna untuk kasus penggunaan yang memerlukan transfer data berdurasi lebih lama dan dimulai oleh pengguna, seperti mendownload file dari server jarak jauh. Jenis tugas ini harus menggunakan tugas transfer data yang dimulai pengguna.

Tugas transfer data yang dimulai pengguna dimulai oleh pengguna. Tugas ini memerlukan notifikasi, segera dimulai, dan mungkin dapat berjalan untuk jangka waktu lama sesuai kondisi sistem. Anda dapat menjalankan beberapa tugas transfer data yang dimulai oleh pengguna secara serentak.

Tugas yang dimulai oleh pengguna harus dijadwalkan saat aplikasi terlihat oleh pengguna (atau dalam salah satu kondisi yang diizinkan). Setelah semua batasan terpenuhi, tugas yang dimulai pengguna dapat dijalankan oleh OS, tunduk pada pembatasan kesehatan sistem. Sistem juga dapat menggunakan estimasi ukuran payload yang disediakan untuk menentukan berapa lama tugas akan dijalankan.

Izin untuk tugas transfer data yang dimulai pengguna

Tugas transfer data yang dimulai pengguna memerlukan izin baru untuk dijalankan: RUN_USER_INITIATED_JOBS. Sistem memberikan izin ini secara otomatis. Sistem akan menampilkan SecurityException jika Anda tidak mendeklarasikan izin dalam manifes aplikasi.

Proses untuk menjadwalkan tugas transfer data yang dimulai pengguna

To run a user initiated job, do the following:

If this is your first time declaring an API with JobScheduler, declare the JobService and associated permissions in your manifest. Also, define a concrete subclass of JobService for your data transfer:

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

class CustomTransferService : JobService() {
  ...
}

Declare the RUN_USER_INITIATED_JOBS permission in your manifest:

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

Call the new setUserInitiated() method when building a JobInfo object. It is also recommended that you offer a payload size estimate by calling setEstimatedNetworkBytes() while creating your job:

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

Schedule the job before the transfer starts, while the application is visible or in the allowed conditions list:

val jobScheduler: JobScheduler =
    context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
jobScheduler.schedule(jobInfo)

When the job is being executed, ensure you call setNotification() on the JobService object. This value is used to make the user aware that the job is running, both in the Task Manager and in the status bar notification area:

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

Periodically update the notification to keep the user informed of the job's status and progress. If you cannot determine the transfer size ahead of scheduling the job, or need to update the estimated transfer size, use the new API, updateEstimatedNetworkBytes() to update the transfer size after it becomes known.
When execution is complete, call jobFinished() to signal to the system that the job is complete, or that the job should be rescheduled.

Tugas transfer data yang dimulai pengguna dapat dihentikan

Pengguna dan sistem dapat menghentikan tugas transfer yang dimulai pengguna.

Oleh pengguna, dari Pengelola Tugas

Pengguna dapat menghentikan tugas transfer data yang dimulai pengguna dan muncul di Pengelola Tugas.

Saat pengguna menekan Stop, sistem akan melakukan hal berikut:

Menghentikan proses aplikasi Anda dengan segera, termasuk semua tugas lain atau layanan latar depan yang sedang berjalan.
Tidak memanggil onStopJob() untuk tugas yang sedang berjalan.
Mencegah tugas yang terlihat oleh pengguna agar tidak dijadwalkan ulang.

Oleh karena itu, sebaiknya berikan kontrol dalam notifikasi yang diposting untuk tugas itu guna memungkinkan penghentian dan penjadwalan ulang tugas dengan baik.

Perlu diperhatikan bahwa, dalam keadaan khusus, tombol Stop tidak akan muncul di samping tugas di Pengelola Tugas, atau tugas tidak ditampilkan sama sekali di Pengelola Tugas.

Oleh sistem

Tidak seperti tugas reguler, tugas transfer data yang dimulai pengguna tidak terpengaruh oleh kuota Bucket Aplikasi Standby. Namun, sistem tetap menghentikan tugas jika salah satu kondisi berikut terjadi:

Batasan yang ditentukan developer tidak lagi terpenuhi.
Sistem menentukan bahwa tugas telah berjalan lebih lama dari yang diperlukan untuk menyelesaikan tugas transfer data.
Sistem perlu memprioritaskan kesehatan sistem dan menghentikan tugas karena peningkatan status termal.
Proses aplikasi dihentikan karena memori perangkat rendah.

Jika tugas dihentikan oleh sistem (bukan oleh kasus memori rendah), sistem akan memanggil onStopJob(), dan sistem akan mencoba kembali tugas pada saat sistem dianggap optimal. Pastikan aplikasi Anda dapat mempertahankan status transfer data, meskipun onStopJob() tidak dipanggil, dan bahwa aplikasi Anda dapat memulihkan status ini saat onStartJob() dipanggil lagi.

Kondisi yang diizinkan untuk menjadwalkan tugas transfer data yang dimulai pengguna

Apps can only start a user-initiated data transfer job if the app is in the visible window, or if the certain conditions are met. To determine when a user-initiated data transfer job can be scheduled, the system applies the same list of conditions that allow apps to start an activity from the background in special cases. Notably, this list of conditions are not the same as the set of exemptions for background-started foreground service restrictions.

The exceptions to the previous statement are the following:

If an app can launch activities from the background, they can also launch user-initiated data transfer jobs from the background.
If an app has an activity in the back stack of an existing task on the Recents screen, that alone doesn't allow a user-initiated data transfer job to run.

If the job is scheduled at some other time not listed in the allowed conditions list, the job fails and returns a RESULT_FAILURE error code.

Batasan yang diizinkan untuk tugas transfer data yang dimulai pengguna

Untuk mendukung tugas agar berjalan pada titik yang optimal, Android menawarkan kemampuan untuk menetapkan batasan bagi setiap jenis tugas. Batasan ini sudah tersedia mulai Android 13.

Catatan: Tabel berikut hanya membandingkan batasan yang bervariasi antara setiap jenis tugas. Lihat halaman developer JobScheduler atau batasan kerja untuk semua batasan.

Tabel berikut menunjukkan berbagai jenis tugas yang mendukung batasan tugas tertentu, serta kumpulan batasan tugas yang didukung WorkManager. Gunakan kotak penelusuran sebelum tabel untuk memfilter tabel berdasarkan nama metode batasan tugas.

Berikut ini batasan yang diizinkan dengan tugas transfer data yang dimulai pengguna:

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

Pengujian

Daftar berikut menunjukkan beberapa langkah untuk menguji tugas aplikasi secara manual:

Untuk mendapatkan ID tugas, dapatkan nilai yang ditentukan saat tugas di-build.
Untuk langsung menjalankan tugas, atau untuk mencoba kembali tugas yang dihentikan, jalankan perintah berikut di jendela terminal:
```
adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID
```
Untuk menyimulasikan penghentian paksa sebuah tugas oleh sistem (karena kondisi sistem atau kondisi kehabisan kuota), jalankan perintah berikut di jendela terminal:
```
adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID
```