Vom Nutzer initiierte Datenübertragung

If you need to perform a data transfer that may take a long time, you can create a JobScheduler job and identify it as a user-initiated data transfer (UIDT) job. UIDT jobs are intended for longer-duration data transfers that are initiated by the device user, such as downloading a file from a remote server. UIDT jobs were introduced with Android 14 (API level 34).

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.

Vom Nutzer initiierte Datenübertragungsvorgänge planen

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

Abwärtskompatibilität

Derzeit gibt es keine Jetpack-Bibliothek, die UIDT-Jobs unterstützt. Aus diesem Grund empfehlen wir, die Änderung mit Code zu versehen, der prüft, ob Sie Android 14 oder höher verwenden. Bei älteren Android-Versionen können Sie die Implementierung des Diensts im Vordergrund von WorkManager als Fallback-Ansatz verwenden.

Hier ist ein Beispiel für Code, der die entsprechende Systemversion prüft:

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-Jobs beenden

Sowohl der Nutzer als auch das System können vom Nutzer initiierte Übertragungsjobs stoppen.

Vom Nutzer über den Task-Manager

Der Nutzer kann einen vom Nutzer initiierten Datenübertragungsvorgang beenden, der im Task-Manager angezeigt wird.

Wenn der Nutzer auf Stopp drückt, geschieht Folgendes:

  • Der Prozess Ihrer App wird sofort beendet, einschließlich aller anderen Jobs oder Dienste im Vordergrund.
  • onStopJob() wird für keine laufenden Jobs aufgerufen.
  • Verhindert, dass nutzersichtbare Jobs neu geplant werden.

Aus diesen Gründen wird empfohlen, in der Benachrichtigung für den Job Steuerelemente bereitzustellen, mit denen der Job ordnungsgemäß beendet und neu geplant werden kann.

Unter bestimmten Umständen wird die Schaltfläche Beenden nicht neben dem Job im Task-Manager angezeigt oder der Job wird im Task-Manager gar nicht angezeigt.

Vom System

Im Gegensatz zu regulären Jobs sind vom Nutzer initiierte Datenübertragungsvorgänge nicht von den Kontingenten für App-Standby-Buckets betroffen. Das System stoppt den Job jedoch weiterhin, wenn eine der folgenden Bedingungen eintritt:

  • Eine vom Entwickler definierte Einschränkung wird nicht mehr erfüllt.
  • Das System stellt fest, dass der Job länger als für die Durchführung der Datenübertragung erforderlich ausgeführt wurde.
  • Das System muss der Systemintegrität Priorität einräumen und Jobs aufgrund eines erhöhten thermischen Zustands beenden.
  • Der App-Prozess wird aufgrund von zu wenig Gerätespeicher beendet.

Wenn der Job vom System aus anderen Gründen als geringem Gerätespeicher beendet wird, ruft das System onStopJob() auf und versucht es zu einem Zeitpunkt noch einmal, der vom System als optimal angesehen wird. Achte darauf, dass deine App den Status der Datenübertragung auch dann beibehalten kann, wenn onStopJob() nicht aufgerufen wird, und dass deine App diesen Status wiederherstellen kann, wenn onStartJob() noch einmal aufgerufen wird.

Bedingungen für das Planen vom Nutzer initiierter Datenübertragungsvorgänge

Apps können einen vom Nutzer initiierten Datenübertragungsvorgang nur starten, wenn sich die App im sichtbaren Fenster befindet oder bestimmte Bedingungen erfüllt sind:

  • Wenn eine App Aktivitäten aus dem Hintergrund starten kann, kann sie auch vom Nutzer initiierte Datenübertragungsjobs aus dem Hintergrund starten.
  • Wenn eine App eine Aktivität im Backstack einer vorhandenen Aufgabe auf dem Bildschirm Letzte hat, ist das allein noch kein Grund, einen vom Nutzer initiierten Datenübertragungsjob auszuführen.

Wenn der Job zu einem Zeitpunkt ausgeführt werden soll, zu dem die erforderlichen Bedingungen nicht erfüllt sind, schlägt er fehl und gibt den Fehlercode RESULT_FAILURE zurück.

Zulässige Einschränkungen für vom Nutzer initiierte Datenübertragungsvorgänge

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

Testen

The following list shows some steps on how to test your app's jobs manually:

  • To get the job ID, get the value that is defined upon the job being built.

  • To run a job immediately, or to retry a stopped job, run the following command in a terminal window:

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

  • To simulate the system force-stopping a job (due to system health or out-of-quota conditions), run the following command in a terminal window:

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

Siehe auch

Zusätzliche Ressourcen

Weitere Informationen zu von Nutzern initiierten Datenübertragungen finden Sie in den folgenden zusätzlichen Ressourcen: