사용자 시작 데이터 전송

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

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

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

참고: 현재 짧은 기간이며 중단 가능한 네트워크 데이터 전송 사용 사례에 WorkManager를 사용하고 있다면 사용자가 시작한 데이터 전송 작업으로 변경하는 대신 WorkManager를 계속 사용하는 것이 좋습니다. UIDT를 사용해야 하는지 여부를 더 잘 이해하려면 데이터 전송 백그라운드 작업 옵션 문서를 참고하세요.

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

사용자가 시작한 데이터 전송 작업을 실행하려면 다음을 실행하세요.

1. 앱이 매니페스트에서 JobService 및 관련 권한을 선언했는지 확인합니다.

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

   데이터 전송을 위해 JobService의 구체적인 하위 클래스도 정의합니다.

   Kotlin

   class CustomTransferService : JobService() {
     ...
   }

   자바

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

2. 매니페스트에서 RUN_USER_INITIATED_JOBS 권한을 선언합니다.

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

3. JobInfo 객체를 빌드할 때 setUserInitiated() 메서드를 호출합니다. (이 메서드는 Android 14부터 사용할 수 있습니다.) 또한 작업을 만드는 동안 setEstimatedNetworkBytes()를 호출하여 페이로드 크기 추정치를 제공하는 것이 좋습니다.

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

   자바

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

4. 작업이 실행되는 동안 JobService 객체에서 setNotification()를 호출합니다. setNotification()를 호출하면 작업 관리자와 상태 표시줄 알림 영역 모두에서 작업이 실행 중임을 사용자에게 알립니다.

   실행이 완료되면 jobFinished()를 호출하여 시스템에 작업이 완료되었거나 작업을 다시 예약해야 한다고 알립니다.

   Kotlin

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

   자바

   class DownloadTransferService 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. 사용자에게 작업의 상태와 진행 상황을 계속 알릴 수 있도록 주기적으로 알림을 업데이트합니다. 작업을 예약하기 전에 전송 크기를 확인할 수 없거나 예상 전송 크기를 업데이트해야 하는 경우 새 API updateEstimatedNetworkBytes()를 사용하여 전송 크기를 파악한 후 업데이트합니다.

권장사항

UIDT 작업을 효과적으로 실행하려면 다음을 수행하세요.

1. 작업이 실행되어야 하는 시점을 지정하려면 네트워크 제약 조건과 작업 실행 제약 조건을 명확하게 정의하세요.

2. onStartJob()에서 비동기적으로 작업을 실행합니다. 예를 들어 코루틴을 사용하여 이 작업을 실행할 수 있습니다. 비동기적으로 작업을 실행하지 않으면 기본 스레드에서 작업이 실행되어 기본 스레드가 차단될 수 있으며 이로 인해 ANR이 발생할 수 있습니다.

3. 필요 이상으로 작업을 실행하지 않으려면 전송이 성공하든 실패하든 전송이 완료되면 jobFinished()를 호출하세요. 이렇게 하면 작업이 필요 이상으로 오래 실행되지 않습니다. 작업이 중지된 이유를 알아보려면 onStopJob() 콜백 메서드를 구현하고 JobParameters.getStopReason()를 호출합니다.

이전 버전과의 호환성

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

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

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

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

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

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.

시스템에 의해

Unlike regular jobs, user-initiated data transfer jobs are unaffected by App Standby Buckets quotas. However, the system still stops the job if any of the following conditions occur:

• A developer-defined constraint is no longer met.
• The system determines that the job has run for longer than necessary to complete the data transfer task.
• The system needs to prioritize system health and stop jobs due to increased thermal state.
• The app process is killed due to low device memory.

When the job is stopped by the system for reasons other than low device memory, the system calls onStopJob(), and the system retries the job at a time that the system deems to be optimal. Make sure that your app can persist the data transfer state even if onStopJob() isn't called, and that your app can restore this state when onStartJob() is called again.

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

只有当应用处于可见窗口中或满足特定条件时，应用才能启动用户发起的数据传输作业：

• 如果应用可以从后台启动 activity，则也可以从后台启动用户发起的数据传输作业。
• 如果应用在最近用过屏幕上现有任务的返回堆栈中有 activity，单靠这一点并不允许运行用户发起的数据传输作业。

注意： 从后台启动 UIDT 作业的条件与允许应用从后台启动前台服务的豁免条件不同。

如果作业安排在未满足必要条件的时间运行，则作业将失败并返回 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()

테스트

下面列出了有关如何手动测试应用作业的一些步骤：

• 如需获取作业 ID，请获取在构建作业时定义的值。

• 如需立即运行作业或重试已停止的作业，请在终端窗口中运行以下命令：

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

• 如需模拟系统强行停止作业（由于系统运行状况或超出配额条件），请在终端窗口中运行以下命令：

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

참고 항목

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

추가 리소스

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

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