Przenoszenie danych inicjowane przez użytkownika

Jeśli musisz przeprowadzić transfer danych, który może potrwać długo, możesz utworzyć zadanie JobScheduler i oznaczyć je jako inicjowane przez użytkownika zadanie przesyłania danych (UIDT). Zadania UIDT są przeznaczone do przesyłania danych przez dłuższy czas, inicjowanego przez użytkownika urządzenia, np. pobierania pliku z serwera zdalnego. Zadania UIDT zostały wprowadzone w Androidzie 14 (poziom API 34).

Zadania przenoszenia danych inicjowane przez użytkownika są uruchamiane przez użytkownika. Te zadania wymagają powiadomienia, rozpoczynają się natychmiast i mogą być wykonywane przez dłuższy czas, jeśli pozwalają na to warunki systemowe. Możesz uruchomić kilka zadań przenoszenia danych inicjowanych przez użytkownika jednocześnie.

Zadania zainicjowane przez użytkownika muszą być zaplanowane, gdy aplikacja jest widoczna dla użytkownika (lub w jednym z dozwolonych stanów). Gdy wszystkie ograniczenia zostaną spełnione, zadania zainicjowane przez użytkownika mogą być wykonywane przez system operacyjny z zastrzeżeniem ograniczeń dotyczących stanu systemu. System może też używać podanego szacowanego rozmiaru ładunku do określania czasu wykonywania zadania.

Planowanie zadań przenoszenia danych inicjowanych przez użytkownika

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

Zgodność wsteczna

Obecnie nie ma biblioteki Jetpack, która obsługuje zadania UIDT. Z tego powodu zalecamy ograniczenie zmiany za pomocą kodu, który sprawdza, czy używasz Androida 14 lub nowszego. W starszych wersjach Androida możesz użyć implementacji usługi na pierwszym planie w WorkManagerze jako metody rezerwowej.

Oto przykład kodu, który sprawdza odpowiednią wersję systemu:

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

Zatrzymywanie zadań UIDT

Zarówno użytkownik, jak i system mogą zatrzymać zadania transferu zainicjowane przez użytkownika.

Przez użytkownika w Menedżerze zadań

Użytkownik może zatrzymać zadanie przesyłania danych inicjowane przez użytkownika, które pojawia się w Menedżerze zadań.

Gdy użytkownik naciśnie Zatrzymaj, system wykona te czynności:

  • natychmiast zakończyć proces aplikacji, w tym wszystkie inne zadania lub usługi działające w tle;
  • Nie wywołuje funkcji onStopJob() w przypadku żadnych uruchomionych zadań.
  • Uniemożliwia przeplanowanie zadań widocznych dla użytkowników.

Z tego powodu zalecamy udostępnienie w powiadomieniu o zadaniu ustawień umożliwiających płynne zatrzymanie i przeplanowanie zadania.

Pamiętaj, że w szczególnych okolicznościach przycisk Zatrzymaj nie będzie widoczny obok zadania w Menedżerze zadań lub zadanie w ogóle nie będzie widoczne w Menedżerze zadań.

przez system,

W przeciwieństwie do zwykłych zadań na zadania przenoszenia danych inicjowane przez użytkownika nie mają wpływu limity zasobników gotowości aplikacji. System nadal jednak zatrzymuje zadanie, jeśli wystąpi którykolwiek z tych warunków:

  • Zdefiniowane przez dewelopera ograniczenie nie jest już spełnione.
  • System stwierdza, że zadanie trwało dłużej niż było to konieczne do ukończenia zadania przesyłania danych.
  • System musi traktować priorytetowo stan systemu i zatrzymywać zadania z powodu zwiększonego stanu termicznego.
  • Proces aplikacji zostaje zakończony z powodu małej ilości pamięci urządzenia.

Jeśli zadanie zostanie zatrzymane przez system z przyczyn innych niż mała ilość pamięci urządzenia, system wywoła funkcję onStopJob() i ponowi próbę wykonania zadania w optymalnym czasie. Upewnij się, że aplikacja może zachować stan przesyłania danych nawet wtedy, gdy funkcja onStopJob() nie jest wywoływana, oraz że może przywrócić ten stan, gdy funkcja onStartJob() zostanie ponownie wywołana.

Warunki, które muszą być spełnione, aby można było zaplanować zadania przesyłania danych inicjowane przez użytkownika

Aplikacje mogą inicjować zadania przesyłania danych inicjowane przez użytkownika tylko wtedy, gdy są widoczne lub gdy są spełnione określone warunki:

  • Jeśli aplikacja może uruchamiać działania w tle, może też uruchamiać zadania przesyłania danych inicjowane przez użytkownika w tle.
  • Jeśli aplikacja ma aktywność w dolnej części stosu istniejącego zadania na ekranie Ostatnie, nie oznacza to, że zadanie przesyłania danych inicjowane przez użytkownika może zostać uruchomione.

Jeśli zadanie jest zaplanowane do wykonania w czasie, gdy nie są spełnione niezbędne warunki, zadanie się nie powiedzie i zwróci kod błędu RESULT_FAILURE.

Ograniczenia dozwolone w przypadku zadań przesyłania danych inicjowanych przez użytkownika

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

Testowanie

Na liście poniżej znajdziesz instrukcje ręcznego testowania zadań aplikacji:

  • Aby uzyskać identyfikator zadania, pobierz wartość zdefiniowaną przy tworzeniu zadania.

  • Aby od razu uruchomić zadanie lub ponownie uruchomić zatrzymane zadanie, uruchom następujące polecenie w oknie terminala:

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

  • Aby symulować zatrzymanie zadania przez system (ze względu na stan systemu lub w warunkach braku limitu), uruchom to polecenie w oknie terminala:

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

Zobacz również

Dodatkowe materiały

Więcej informacji o zainicjowanych przez użytkownika transferach danych znajdziesz w tych dodatkowych materiałach: