Kullanıcı tarafından başlatılan veri aktarımı

If you need to perform a data transfer that may take a long time, you can create a JobScheduler job and identify it as a user-initiated data transfer (UIDT) job. UIDT jobs are intended for longer-duration data transfers that are initiated by the device user, such as downloading a file from a remote server. UIDT jobs were introduced with Android 14 (API level 34).

User-initiated data transfer jobs are started by the user. These jobs require a notification, start immediately, and may be able to run for an extended period of time as system conditions allow. You can run several user-initiated data transfer jobs concurrently.

User initiated jobs must be scheduled while the application is visible to the user (or in one of the allowed conditions). After all constraints are met, user initiated jobs can be executed by the OS, subject to system health restrictions. The system may also use the provided estimated payload size to determine how long the job executes.

Kullanıcı tarafından başlatılan veri aktarımı işlerini planlama

Kullanıcı tarafından başlatılan bir veri aktarımı işini çalıştırmak için aşağıdakileri yapın:

  1. Uygulamanızın manifest dosyasında JobService ve ilişkili izinlerin beyan edildiğinden emin olun:

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

    Ayrıca, veri aktarımınız için JobService öğesinin somut bir alt sınıfını tanımlayın:

    Kotlin

    class CustomTransferService : JobService() {   ... }

    Java

    class CustomTransferService extends JobService() {      ....  }

  2. Manifest dosyasında RUN_USER_INITIATED_JOBS iznini beyan edin:

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

  3. setUserInitiated() yöntemini bir JobInfo nesnesi oluştururken çağırın. (Bu yöntem, Android 14'ten itibaren kullanılabilir.) Ayrıca, işinizi oluştururken setEstimatedNetworkBytes() işlevini çağırarak bir yük boyutu tahmini sunmanızı öneririz.

    Kotlin

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

    Java

    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, CustomTransferService.class))     // ...     .setUserInitiated(true)     .setRequiredNetwork(networkRequest)     // Provide your estimate of the network traffic here     .setEstimatedNetworkBytes(1024 * 1024 * 1024)     // ...     .build();

  4. İş yürütülürken JobService nesnesinde setNotification() işlevini çağırın. Calling setNotification(), hem Görev Yöneticisi'nde hem de durum çubuğu bildirim alanında kullanıcının işin çalıştığından haberdar olmasını sağlar.

    Yürütme tamamlandığında, işin tamamlandığını veya yeniden planlanması gerektiğini sisteme bildirmek için jobFinished() işlevini çağırın.

    Kotlin

    class CustomTransferService: 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     } }

    Java

    class CustomTransferService 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. Kullanıcıyı işin durumu ve ilerleme durumu hakkında bilgilendirmek için bildirimi düzenli olarak güncelleyin. İşi planlamadan önce aktarım boyutunu belirleyemiyorsanız veya tahmini aktarım boyutunu güncellemeniz gerekiyorsa aktarım boyutu bilindikten sonra güncellemek için yeni API'yi (updateEstimatedNetworkBytes()) kullanın.

Öneriler

UIDT işlerini etkili bir şekilde çalıştırmak için aşağıdakileri yapın:

  1. İşin ne zaman yürütülmesi gerektiğini belirtmek için ağ kısıtlamalarını ve iş yürütme kısıtlamalarını net bir şekilde tanımlayın.

  2. Görevi onStartJob() içinde eşzamansız olarak yürütün. Örneğin, bunu eş yordam kullanarak yapabilirsiniz. Görevi eşzamanlı olarak çalıştırmazsanız çalışma ana iş parçacığında çalışır ve onu engelleyebilir. Bu durum ANR'ye neden olabilir.

  3. İşin gereğinden uzun süre çalışmasını önlemek için aktarım başarılı olsa da olmasa da tamamlandığında jobFinished() işlevini çağırın. Böylece iş, gerekenden daha uzun sürmez. Bir işin neden durdurulduğunu öğrenmek için onStopJob() geri çağırma yöntemini uygulayın ve JobParameters.getStopReason() yöntemini çağırın.

Geriye dönük uyumluluk

Şu anda UIDT işlerini destekleyen bir Jetpack kitaplığı yoktur. Bu nedenle, değişikliğinizi Android 14 veya daha yeni bir sürümde çalıştığınızı doğrulayan bir kodla sınırlamanızı öneririz. Daha düşük Android sürümlerinde, alternatif bir yaklaşım olarak WorkManager'ın ön plan hizmeti uygulamasını kullanabilirsiniz.

Aşağıda, uygun sistem sürümünü kontrol eden bir kod örneği verilmiştir:

Kotlin

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

Java

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

Hem kullanıcı hem de sistem, kullanıcı tarafından başlatılan aktarım işlerini durdurabilir.

Kullanıcı tarafından, görev yöneticisinden

The user can stop a user-initiated data transfer job that appears in the Task Manager.

At the moment that the user presses Stop, the system does the following:

  • Terminates your app's process immediately, including all other jobs or foreground services running.
  • Doesn't call onStopJob() for any running jobs.
  • Prevents user-visible jobs from being rescheduled.

For these reasons, it's recommended to provide controls in the notification posted for the job to allow gracefully stopping and rescheduling the job.

Note that, under special circumstances, the Stop button doesn't appear next to the job in the Task Manager, or the job isn't shown in the Task Manager at all.

Sistem tarafından

Kullanıcı tarafından başlatılan veri aktarımı işleri, normal işlerin aksine uygulama bekleme modu grupları kotalarından etkilenmez. Ancak aşağıdaki koşullardan herhangi biri gerçekleşirse sistem işi durdurur:

  • Geliştirici tarafından tanımlanan bir kısıtlama artık karşılanmıyor.
  • Sistem, işin veri aktarımı görevini tamamlamak için gerekenden daha uzun süre çalıştığını belirler.
  • Sistemin, sistem sağlığına öncelik vermesi ve artan termal durum nedeniyle işleri durdurması gerekir.
  • Cihaz belleği azaldığı için uygulama işlemi sonlandırıldı.

İş, cihaz belleğinin az olması dışındaki nedenlerle sistem tarafından durdurulduğunda sistem onStopJob() işlevini çağırır ve işi sistemin en uygun zaman olarak belirlediği bir zamanda yeniden dener. Uygulamanızın, onStopJob() çağrılmasa bile veri aktarımı durumunu koruyabildiğinden ve onStartJob() tekrar çağrıldığında bu durumu geri yükleyebildiğinden emin olun.

Kullanıcı tarafından başlatılan veri aktarımı işlerinin planlanmasına izin verilen koşullar

Uygulamalar, yalnızca görünür penceredeyse veya belirli koşullar karşılanıyorsa kullanıcı tarafından başlatılan bir veri aktarımı işi başlatabilir:

  • Bir uygulama arka plandan etkinlik başlatabiliyorsa kullanıcı tarafından başlatılan veri aktarımı işlerini de arka plandan başlatabilir.
  • Bir uygulamanın En son ekranındaki mevcut bir görevin arka yığınında etkinliği varsa bu durum tek başına kullanıcı tarafından başlatılan veri aktarma işinin çalışmasına izin vermez.
unutulmamalıdır.

Görev, gerekli koşulların karşılanmadığı bir zamanda çalışacak şekilde planlanırsa başarısız olur ve RESULT_FAILURE hata kodu döndürür.

Kullanıcı tarafından başlatılan veri aktarımı işlerine izin verilen kısıtlamalar

Android, en uygun noktalarda çalışan işleri desteklemek için her iş türüne kısıtlamalar atama olanağı sunar. Bu kısıtlamalar Android 13'ten itibaren kullanılabilir.

Not: Aşağıdaki tabloda yalnızca her iş türü arasında farklılık gösteren kısıtlamalar karşılaştırılmaktadır. Tüm kısıtlamalar için JobScheduler geliştirici sayfası veya iş kısıtlamaları sayfasına bakın.

Aşağıdaki tabloda, belirli bir iş kısıtlamasını destekleyen farklı iş türlerinin yanı sıra WorkManager'ın desteklediği iş kısıtlamaları kümesi gösterilmektedir. Tabloyu bir iş kısıtlama yönteminin adına göre filtrelemek için tablonun önündeki arama çubuğunu kullanın.

Kullanıcı tarafından başlatılan veri aktarım işlerinde izin verilen kısıtlamalar şunlardır:

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

Test

The following list shows some steps on how to test your app's jobs manually:

  • To get the job ID, get the value that is defined upon the job being built.

  • To run a job immediately, or to retry a stopped job, run the following command in a terminal window:

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

  • To simulate the system force-stopping a job (due to system health or out-of-quota conditions), run the following command in a terminal window:

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

Ayrıca bkz.

Ek kaynaklar

Kullanıcı tarafından başlatılan veri aktarımları hakkında daha fazla bilgi için aşağıdaki ek kaynaklara bakın: