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

Uzun sürebilecek bir veri aktarımı yapmanız gerekiyorsa JobScheduler işi oluşturabilir ve bunu kullanıcı tarafından başlatılan veri aktarımı (UIDT) işi olarak tanımlayabilirsiniz. UIDT işleri, cihaz kullanıcısı tarafından başlatılan uzun süreli veri aktarımları (ör. uzaktaki bir sunucudan dosya indirme) için tasarlanmıştır. UIDT işleri, Android 14 (API düzeyi 34) ile kullanıma sunuldu.

Kullanıcı tarafından başlatılan veri aktarımı işleri, kullanıcı tarafından başlatılır. Bu işlerin bildirim görüntülemesi ve hemen başlaması gerekir. Bu işler, sistem koşulları izin verirse uzun süre boyunca çalıştırılabilir. Kullanıcı tarafından başlatılan birden fazla veri aktarımı işini eşzamanlı olarak çalıştırabilirsiniz.

Kullanıcı tarafından başlatılan işler, uygulamanın kullanıcı tarafından görülebildiği zaman (veya izin verilen koşullardan birinde) planlanmalıdır. Kullanıcı tarafından başlatılan işler, tüm koşullar karşılandıktan sonra sistem sağlığı kısıtlamalarına tabi olarak işletim sistemi tarafından yürütülebilir. Sistem, işin ne kadar süre boyunca yürütüleceğini belirlemek için sağlanan tahmini yük boyutunu da kullanabilir.

Not: Kısa süreli ve kesintiye uğrayabilen ağ veri aktarımı kullanım alanları için şu anda WorkManager'ı kullanıyorsanız kullanıcı tarafından başlatılan veri aktarım işlerine geçmek yerine WorkManager'ı kullanmaya devam etmenizi öneririz. UIDT kullanıp kullanmamanız gerektiğini daha iyi anlamak için Veri aktarımı arka plan görevi seçenekleri dokümanına bakın.

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, 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, 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, WorkManager'ın ön plan hizmeti uygulamasını yedek yaklaşım olarak 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

Kullanıcı, Görev Yöneticisi'nde görünen kullanıcı tarafından başlatılan bir veri aktarımı işini durdurabilir.

Kullanıcı Durdur'a bastığında sistem aşağıdakileri yapar:

• Çalışan diğer tüm işler veya ön plan hizmetleri dahil olmak üzere uygulamanızın işlemini anında sonlandırır.
• Çalışan işler için onStopJob() çağrılmaz.
• Kullanıcı tarafından görülebilen işlerin yeniden planlanmasını engeller.

Bu nedenle, işin sorunsuz bir şekilde durdurulmasına ve yeniden planlanmasına olanak tanımak için iş için yayınlanan bildirimde kontroller sağlamanız önerilir.

Özel durumlarda Görev Yöneticisi'nde işin yanında Durdur düğmesinin görünmediğini veya işin Görev Yöneticisi'nde hiç gösterilmediğini unutmayın.

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.

Not: UIDT işini arka plandan başlatma koşullarının ön plan hizmetlerini arka plandan başlatmasına izin veren muafiyetler ile aynı olmadığı

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 提供了为每种作业类型分配约束条件的功能。这些约束条件从 Android 13 开始就已经可用。

注意：下表仅比较了因作业类型而异的约束条件。如需了解所有约束条件，请参阅 JobScheduler 开发者页面或工作约束条件。

下表显示了支持给定作业约束条件的不同作业类型，以及 WorkManager 支持的作业约束条件集。您可以使用表格前的搜索栏按作业约束方法的名称过滤表格。

以下是用户发起的数据传输作业允许使用的约束条件：

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

Test

Aşağıdaki listede, uygulamanızın işlerini manuel olarak test etmeye yönelik bazı adımlar gösterilmektedir:

• İş kimliğini almak için, geliştirilmekte olan işin ardından tanımlanan değeri alın.

• Bir işi hemen çalıştırmak veya durdurulan bir işi yeniden denemek için aşağıdaki komutu çalıştırın komutunu girin:

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

• Bir işi zorla durdurması için sistemi simüle etmek (sistem durumu veya (kota dışı koşullar) bir terminal penceresinde aşağıdaki komutu çalıştırın:

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

Ayrıca bkz.

• Arka plan görevlerine genel bakış
• Veri aktarımı arka plan görevi seçenekleri

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:

• UIDT entegrasyonuyla ilgili örnek olay: Google Haritalar, kullanıcı tarafından başlatılan veri aktarımı API'sini kullanarak indirme güvenilirliğini% 10 artırdı