포그라운드 서비스를 사용자가 시작한 데이터 전송 작업으로 이전

Android 14 applies strict rules on when apps are allowed to use foreground services.

Also in Android 14 we are introducing a new API to specify that a job must be a user-initiated data transfer job. This API is helpful for use cases that require longer-duration, user-initiated transferring of data, such as downloading a file from a remote server. These types of tasks should use a user-initiated data transfer job.

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.

사용자가 시작한 데이터 전송 작업에 대한 권한

사용자가 시작한 데이터 전송 작업을 실행하려면 새로운 권한(RUN_USER_INITIATED_JOBS)이 필요합니다. 시스템에서 자동으로 이 권한을 부여합니다. 앱 매니페스트에서 이 권한을 선언하지 않으면 시스템에서 SecurityException이 발생합니다.

사용자가 시작한 데이터 전송 작업을 예약하는 프로세스

사용자가 시작한 작업을 실행하려면 다음을 실행하세요.

1. JobScheduler로 API를 처음 선언하는 경우 매니페스트에서 JobService 및 관련 권한을 선언합니다. 또한 데이터 전송을 위한 구체적인 JobService 서브클래스를 정의합니다.

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

   class CustomTransferService : JobService() {
     ...
   }
   

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

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

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

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

4. 애플리케이션이 표시되거나 허용된 조건 목록에 있는 동안 전송이 시작되기 전에 작업을 예약합니다.

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

5. 작업이 실행되는 동안 JobService 객체에서 setNotification()을 호출해야 합니다. 이 값은 작업 관리자 및 상태 표시줄 알림 영역에서 모두 작업이 실행 중임을 사용자에게 알리는 데 사용됩니다.

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

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

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

사용자가 시작한 데이터 전송 작업을 중지할 수 있음

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

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

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

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

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

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

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

시스템에 의해

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 (not by the low-memory case), the system calls onStopJob(), and the system retries the job at a time that the system deems to be optimal. Check that your app can persist data transfer state, even if onStopJob() isn't called, and that your app can restore this state when onStartJob() is called again.

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

앱은 표시되는 창에 있거나 특정 조건이 충족되는 경우에만 사용자가 시작한 데이터 전송 작업을 시작할 수 있습니다. 사용자가 시작한 데이터 전송 작업을 예약할 수 있는 시기를 판단하기 위해 시스템은 특별한 경우에 앱이 백그라운드에서 활동을 시작하도록 허용하는 동일한 조건 목록을 적용합니다. 이 조건 목록은 백그라운드에서 시작된 포그라운드 서비스 제한의 예외 집합과 동일하지 않습니다.

이전 문에 대한 예외는 다음과 같습니다.

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

작업이 허용된 조건 목록에 나열되지 않은 다른 시간에 예약되면 작업이 실패하고 RESULT_FAILURE 오류 코드가 반환됩니다.

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

To support jobs running at optimal points, Android offers the ability to assign constraints to each job type. These constraints are already 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