사용자 시작 데이터 전송

시간이 오래 걸릴 수 있는 데이터 전송을 실행해야 하는 경우 JobScheduler 작업을 만들고 이를 사용자 시작 데이터 전송 (UIDT) 작업으로 식별하면 됩니다. UIDT 작업은 원격 서버에서 파일을 다운로드하는 등 기기 사용자가 시작하는 장기 데이터 전송을 위한 것입니다. UIDT 작업은 Android 14 (API 수준 34)에서 도입되었습니다.

사용자 시작 데이터 전송 작업은 사용자가 시작합니다. 이러한 작업은 알림이 필요하고, 즉시 시작되며, 시스템 조건에서 허용하는 한 장시간 실행될 수 있습니다. 사용자가 시작한 데이터 전송 작업 여러 개를 동시에 실행할 수 있습니다.

사용자가 시작한 작업은 애플리케이션이 사용자에게 표시되는 동안 (또는 허용된 조건 중 하나로) 예약되어야 합니다. 모든 제약 조건이 충족되면 시스템 상태 제한에 따라 OS에서 사용자가 시작한 작업을 실행할 수 있습니다. 또한 시스템은 제공된 예상 페이로드 크기를 사용하여 작업 실행 시간을 판단할 수도 있습니다.

사용자가 시작한 데이터 전송 작업 예약

To run a user initiated data-transfer job, do the following:

1. Make sure your app has declared the JobService and associated permissions in its manifest:

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

   Also, define a concrete subclass of JobService for your data transfer:

   Kotlin

   class CustomTransferService : JobService() {
     ...
   }

   Java

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

2. Declare the RUN_USER_INITIATED_JOBS permission in the manifest:

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

3. Call the setUserInitiated() method when building a JobInfo object. (This method is available beginning with Android 14.) We also recommend that you offer a payload size estimate by calling setEstimatedNetworkBytes() while creating your job.

   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. While the job is being executed, call setNotification() on the JobService object. Calling setNotification() makes the user aware that the job is running, both in the Task Manager and in the status bar notification area.

   When execution is complete, call jobFinished() to signal to the system that the job is complete, or that the job should be rescheduled.

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

Recommendations

To run UIDT jobs effectively, do the following:

1. Clearly define network constraints and job execution constraints to specify when the job should be executed.

2. Execute the task asynchronously in onStartJob(); for example, you can do this by using a coroutine. If you don't run the task asynchronously, the work runs on the main thread and might block it, which can cause an ANR.

3. To avoid running the job longer than necessary, call jobFinished() when the transfer finishes, whether it succeeds or fails. That way, the job doesn't run longer than necessary. To discover why a job was stopped, implement the onStopJob() callback method and call JobParameters.getStopReason().

이전 버전과의 호환성

현재 UIDT 작업을 지원하는 Jetpack 라이브러리는 없습니다. 따라서 Android 14 이상에서 실행 중인지 확인하는 코드로 변경사항을 관리하는 것이 좋습니다. 하위 Android 버전에서는 WorkManager의 포그라운드 서비스 구현을 대체 접근 방식으로 사용할 수 있습니다.

다음은 적절한 시스템 버전을 확인하는 코드의 예입니다.

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

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 작업 중지

사용자와 시스템 모두 사용자가 시작한 전송 작업을 중지할 수 있습니다.

작업 관리자에서 사용자에 의해

사용자는 작업 관리자에 표시되는 사용자 시작 데이터 전송 작업을 중지할 수 있습니다.

사용자가 중지를 누르면 시스템은 다음 작업을 실행합니다.

• 실행 중인 다른 모든 작업 또는 포그라운드 서비스를 포함하여 앱의 프로세스를 즉시 종료합니다.
• 실행 중인 작업의 onStopJob()을 호출하지 않습니다.
• 사용자에게 표시되는 작업의 일정이 변경되는 것을 방지합니다.

따라서 작업을 단계적으로 중지하고 일정을 변경할 수 있도록 작업에 관해 게시된 알림에 컨트롤을 제공하는 것이 좋습니다.

특수한 상황에서는 중지 버튼이 작업 관리자의 작업 옆에 표시되지 않거나 작업이 작업 관리자에 아예 표시되지 않을 수 있습니다.

시스템에 의해

일반 작업과 달리 사용자가 시작한 데이터 전송 작업은 앱 대기 버킷 할당량의 영향을 받지 않습니다. 그러나 다음 조건 중 하나가 발생하면 시스템은 여전히 작업을 중지합니다.

• 개발자가 정의한 제약 조건이 더 이상 충족되지 않습니다.
• 작업이 데이터 전송 작업을 완료하는 데 필요한 시간보다 오래 실행되었다고 시스템에서 판단합니다.
• 시스템이 시스템 상태를 우선하고 열 상태 증가로 인해 작업을 중지해야 합니다.
• 기기 메모리가 부족하여 앱 프로세스가 종료됩니다.

기기 메모리 부족 이외의 이유로 작업이 시스템에 의해 중지되면 시스템은 onStopJob()을 호출하고 최적으로 간주하는 시점에 작업을 재시도합니다. onStopJob()이 호출되지 않더라도 앱이 데이터 전송 상태를 유지할 수 있는지, onStartJob()이 다시 호출되면 앱이 이 상태를 복원할 수 있는지 확인합니다.

사용자가 시작한 데이터 전송 작업을 예약할 수 있는 조건

앱은 표시되는 창에 있거나 특정 조건이 충족되는 경우에만 사용자가 시작한 데이터 전송 작업을 시작할 수 있습니다.

• 앱이 백그라운드에서 활동을 실행할 수 있는 경우 사용자가 시작한 데이터 전송 작업도 백그라운드에서 실행할 수 있습니다.
• 앱의 최근 화면에 있는 기존 작업의 백 스택에 활동이 있어도 이것만으로는 사용자가 시작한 데이터 전송 작업을 실행할 수 없습니다.

필요한 조건이 충족되지 않는 시간에 작업이 실행되도록 예약되면 작업이 실패하고 RESULT_FAILURE 오류 코드가 반환됩니다.

사용자가 시작한 데이터 전송 작업에 허용되는 제약 조건

To support jobs running at optimal points, Android offers the ability to assign constraints to each job type. These constraints are available as of Android 13.

Note: The following table only compares the constraints that vary between each job type. See JobScheduler developer page or work constraints for all constraints.

The following table shows the different job types that support a given job constraint, as well as the set of job constraints that WorkManager supports. Use the search bar before the table to filter the table by the name of a job constraint method.

These are the constraints allowed with user-initiated data transfer jobs:

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

테스트

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

참고 항목

• 백그라운드 작업 개요
• 데이터 전송 백그라운드 작업 옵션

추가 리소스

사용자 시작 데이터 전송에 관한 자세한 내용은 다음 추가 리소스를 참고하세요.

• UIDT 통합 사례 연구: Google 지도에서 사용자 시작 데이터 전송 API를 사용하여 다운로드 안정성 10% 개선