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ń związanych ze stanem 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:

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

    ....

}

Declare the RUN_USER_INITIATED_JOBS permission in the manifest:

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

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

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

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:

Clearly define network constraints and job execution constraints to specify when the job should be executed.
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.
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 aplikacja działa na Androidzie 14 lub nowszym. W przypadku starszych wersji 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

Apps can only start a user-initiated data transfer job if the app is in the visible window, or if certain conditions are met:

If an app can launch activities from the background, it can also launch user-initiated data transfer jobs from the background.
If an app has an activity in the back stack of an existing task on the Recents screen, that alone doesn't allow a user-initiated data transfer job to run.

If the job is scheduled to run at a time when the necessary conditions are not met, the job fails and returns a RESULT_FAILURE error code.

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

Aby obsługiwać zadania uruchamiane w optymalnych momentach, Android umożliwia przypisywanie ograniczeń do każdego typu zadania. Te ograniczenia są dostępne od Androida 13.

Uwaga: w tej tabeli porównano tylko ograniczenia, które różnią się w zależności od typu zadania. Wszystkie ograniczenia znajdziesz na stronie dla deweloperów JobScheduler lub w sekcji ograniczenia zadań.

W tabeli poniżej znajdziesz różne typy zadań, które obsługują dane ograniczenie zadania, a także zestaw ograniczeń zadań obsługiwanych przez WorkManager. Użyj paska wyszukiwania przed tabelą, aby filtrować tabelę według nazwy metody ograniczenia zadania.

Oto ograniczenia dozwolone w przypadku zadań przesyłania danych inicjowanych przez użytkownika:

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:

Studium przypadku dotyczące integracji UIDT: dzięki interfejsowi User Initiated Data Transfer API Mapy Google zwiększyły niezawodność pobierania o 10%

Przenoszenie danych inicjowane przez użytkownika Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Planowanie zadań przenoszenia danych inicjowanych przez użytkownika

Kotlin

Java

Kotlin

Java

Kotlin

Java

Recommendations

Zgodność wsteczna

Kotlin

Java

Zatrzymywanie zadań UIDT

Przez użytkownika w Menedżerze zadań

przez system,

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

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

Testowanie

Zobacz również

Dodatkowe materiały

Przenoszenie danych inicjowane przez użytkownika