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

Untuk menjalankan tugas yang dimulai pengguna, lakukan hal berikut:

Jika ini pertama kalinya Anda mendeklarasikan API dengan JobScheduler, deklarasikan JobService dan izin terkait dalam manifes Anda. Selain itu, tentukan subclass konkret JobService untuk transfer data Anda:

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

class CustomTransferService : JobService() {
  ...
}

Deklarasikan izin RUN_USER_INITIATED_JOBS dalam manifes Anda:

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

Panggil metode setUserInitiated() baru saat mem-build objek JobInfo. Sebaiknya Anda juga menawarkan estimasi ukuran payload dengan memanggil setEstimatedNetworkBytes() ketika membuat tugas:

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

Jadwalkan tugas sebelum transfer dimulai, saat aplikasi terlihat atau dalam daftar kondisi yang diizinkan:

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

Saat tugas dieksekusi, pastikan Anda memanggil setNotification() pada objek JobService. Nilai ini digunakan untuk membuat pengguna menyadari bahwa tugas sedang berjalan, baik di Pengelola Tugas maupun di area notifikasi status bar:

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

Perbarui notifikasi secara berkala untuk terus memberikan informasi kepada pengguna tentang status dan progres tugas. Jika Anda tidak dapat menentukan ukuran transfer sebelum menjadwalkan tugas, atau perlu memperbarui perkiraan ukuran transfer, gunakan API baru, updateEstimatedNetworkBytes() untuk memperbarui ukuran transfer setelah diketahui.
Setelah eksekusi selesai, panggil jobFinished() untuk memberi tahu sistem bahwa tugas telah selesai, atau tugas tersebut harus dijadwalkan ulang.

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

Aplikasi hanya dapat memulai tugas transfer data yang dimulai pengguna jika aplikasi berada di jendela yang terlihat, atau jika kondisi tertentu terpenuhi. Untuk menentukan kapan tugas transfer data yang dimulai pengguna dapat dijadwalkan, sistem akan menerapkan daftar kondisi yang sama, yang memungkinkan aplikasi memulai aktivitas dari latar belakang dalam kasus yang khusus. Secara khusus, daftar kondisi ini tidak sama dengan kumpulan pengecualian untuk batasan layanan latar depan yang dimulai di latar belakang.

Pengecualian untuk pernyataan sebelumnya adalah sebagai berikut:

Jika aplikasi dapat meluncurkan aktivitas dari latar belakang, aplikasi juga dapat meluncurkan tugas transfer data yang dimulai pengguna dari latar belakang.
Jika aplikasi memiliki aktivitas di data sebelumnya dari tugas yang ada di layar Terbaru, hal tersebut tidak memungkinkan tugas transfer data yang dimulai pengguna dijalankan.

Jika tugas dijadwalkan pada waktu lain yang tidak tercantum dalam daftar kondisi yang diizinkan, tugas akan gagal dan menampilkan kode error RESULT_FAILURE.

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