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

Android 14에서는 앱이 포그라운드 서비스를 사용할 수 있는 경우에 엄격한 규칙을 적용합니다.

또한 Android 14에서는 작업이 사용자가 시작한 데이터 전송 작업이어야 한다고 지정하는 새 API를 도입합니다. 이 API는 원격 서버에서 파일을 다운로드하는 등 사용자가 시작한 장기 데이터 전송이 필요한 사용 사례에 유용합니다. 이러한 유형의 작업은 사용자 시작 데이터 전송 작업을 사용해야 합니다.

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

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

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

사용자가 시작한 데이터 전송 작업을 실행하려면 새로운 권한(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()를 호출하여 시스템에 작업이 완료되었거나 작업을 다시 예약해야 한다고 알립니다.

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

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

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

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

시스템에 의해

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

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

작업이 메모리가 부족한 사례가 아닌 시스템에 의해 중지되면 시스템은 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 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