העברת נתונים ביוזמת המשתמש

אם אתם צריכים לבצע העברת נתונים שעשויה להימשך זמן רב, אתם יכולים ליצור משימה ב-JobScheduler ולזהות אותה כמשימה של העברת נתונים ביוזמת המשתמש (UIDT). משימות UIDT מיועדות להעברות נתונים לטווח ארוך שמופעלות על ידי משתמש המכשיר, כמו הורדת קובץ משרת מרוחק. התכונה 'משימות UIDT' הושקה ב-Android 14 (רמת API 34).

משימות של העברת נתונים ביוזמת המשתמשים מופעלות על ידי המשתמשים. העבודות האלה דורשות הודעה, מתחילות באופן מיידי ויכולות לפעול למשך תקופה ממושכת, בהתאם לתנאי המערכת. אפשר להריץ כמה משימות של העברת נתונים ביוזמת המשתמשים בו-זמנית.

צריך לתזמן משימות שהמשתמש מפעיל בזמן שהאפליקציה גלויה למשתמש (או באחד מהתנאים המותרים). אחרי שכל האילוצים מתקיימים, מערכת ההפעלה יכולה להריץ משימות שהמשתמש יזום, בכפוף למגבלות של תקינות המערכת. יכול להיות שהמערכת תשתמש גם בגודל המטען הייעודי (payload) המשוער שסיפקתם כדי לקבוע את משך הביצוע של העבודה.

תזמון משימות של העברת נתונים שהפעילו משתמשים

כדי להריץ משימה של העברת נתונים ביוזמת המשתמשים:

1. מוודאים שהאפליקציה הצהירה על JobService ועל ההרשאות המשויכות בקובץ המניפסט שלה:

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

   בנוסף, מגדירים מחלקת משנה קונקרטית של JobService להעברת הנתונים:

   Kotlin

   class CustomTransferService : JobService() {
     ...
   }

   Java

   class CustomTransferService extends JobService() {
   
       ....
   
   }

2. מצהירים על ההרשאה RUN_USER_INITIATED_JOBS במניפסט:

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

3. מבצעים קריאה ל-method‏ setUserInitiated() כשיוצרים אובייקט JobInfo. (השיטה הזו זמינה החל מ-Android 14). מומלץ גם להעריך את גודל המטען הייעודי על ידי קריאה ל-setEstimatedNetworkBytes() במהלך יצירת העבודה.

   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. בזמן שהעבודה מתבצעת, מפעילים את הפונקציה call setNotification() באובייקט JobService. הפונקציה Calling setNotification() מודיעה למשתמש שהעבודה פועלת, גם במנהל המשימות וגם באזור ההודעות של סרגל המצב.

   כשההפעלה מסתיימת, קוראים ל-jobFinished() כדי לסמן למערכת שהעבודה הסתיימה או שצריך לתזמן מחדש את העבודה.

   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. מעדכנים את ההתראה מעת לעת כדי שהמשתמש יקבל מידע על הסטטוס וההתקדמות של העבודה. אם אתם לא יכולים לקבוע את גודל ההעברה לפני שתזמנו את העבודה, או אם אתם צריכים לעדכן את גודל ההעברה המשוער, אתם יכולים להשתמש ב-API החדש, updateEstimatedNetworkBytes(), כדי לעדכן את גודל ההעברה אחרי שהוא ידוע.

המלצות

כדי להריץ ביעילות משימות של UIDT, צריך לבצע את הפעולות הבאות:

1. הגדירו בבירור את האילוצים של הרשת ואת האילוצים של הרצת העבודה כדי לציין מתי העבודה צריכה להתבצע.

2. להריץ את המשימה באופן אסינכרוני ב-onStartJob(). לדוגמה, אפשר לעשות את זה באמצעות קורוטינה. אם לא מריצים את המשימה באופן אסינכרוני, העבודה מתבצעת ב-thread הראשי והיא עלולה לחסום אותו, מה שיכול לגרום ל-ANR.

3. כדי למנוע הרצה של העבודה למשך זמן ארוך מהנדרש, צריך להתקשר אל jobFinished() כשההעברה מסתיימת, בין אם היא מצליחה ובין אם היא נכשלת. כך העבודה לא תפעל יותר מהזמן הנדרש. כדי לגלות למה משימה הופסקה, צריך להטמיע את שיטת הקריאה החוזרת (callback) onStopJob() ולקרוא ל-JobParameters.getStopReason().

תאימות לאחור

There is currently no Jetpack library that supports UIDT jobs. For this reason, we recommend that you gate your change with code that verifies that you're running on Android 14 or higher. On lower Android versions, you can use WorkManager's foreground service implementation as a fallback approach.

Here's an example of code that checks for the appropriate system version:

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

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

גם המשתמש וגם המערכת יכולים לעצור העברות שהמשתמש יזם.

על ידי המשתמש, דרך מנהל המשימות

המשתמש יכול להפסיק משימה להעברת נתונים שהמשתמש יזם, שמופיעה במנהל המשימות.

ברגע שהמשתמש לוחץ על Stop, המערכת מבצעת את הפעולות הבאות:

• סיום מיידי של תהליך האפליקציה, כולל כל המשימות או השירותים האחרים שפועלים בחזית.
• לא מתבצעת קריאה ל-onStopJob() לגבי משימות שפועלות.
• מניעת תזמון מחדש של משימות שגלויות למשתמשים.

לכן מומלץ לספק אמצעי בקרה בהודעה שמתפרסמת לגבי המשימה, כדי לאפשר להפסיק את המשימה בצורה תקינה ולתזמן אותה מחדש.

חשוב לדעת שבנסיבות מיוחדות, הלחצן Stop לא מופיע לצד המשימה במנהל המשימות, או שהמשימה לא מוצגת בכלל במנהל המשימות.

על ידי המערכת

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

תנאים שמאפשרים לתזמן משימות של העברת נתונים שהמשתמשים יזמו

אפליקציות יכולות להתחיל משימת העברת נתונים ביוזמת משתמש רק אם האפליקציה נמצאת בחלון הגלוי, או אם מתקיימים תנאים מסוימים:

• אם אפליקציה יכולה להפעיל פעילויות מהרקע, היא יכולה גם להפעיל מהרקע משימות העברת נתונים שהמשתמשים יזמו.
• אם לאפליקציה יש פעילות בסטאק העורפי של משימה קיימת במסך מהזמן האחרון, זה לא מאפשר להפעיל משימה להעברת נתונים ביוזמת המשתמש.

אם המשימה מתוזמנת לפעול בזמן שבו התנאים הנדרשים לא מתקיימים, היא תיכשל ותוחזר לה קוד השגיאה RESULT_FAILURE.

מגבלות שמותרות לעבודות של העברת נתונים שהמשתמשים יזמו

כדי לתמוך בהרצת משימות בנקודות אופטימליות, מערכת Android מאפשרת להקצות אילוצים לכל סוג משימה. האילוצים האלה זמינים החל מ-Android 13.

הערה: בטבלה הבאה מוצגות רק המגבלות שמשתנות בין כל סוג משימה. כל האילוצים מפורטים בדף המפתחים של JobScheduler או באילוצים של עבודות.

בטבלה הבאה מוצגים סוגי העבודות השונים שתומכים באילוצי עבודה מסוימים, וגם קבוצת אילוצי העבודה ש-WorkManager תומך בהם. אפשר להשתמש בסרגל החיפוש שמעל הטבלה כדי לסנן את הטבלה לפי השם של שיטת אילוץ של משימה.

אלה המגבלות שאפשר להגדיר למשימות של העברת נתונים ביוזמת המשתמשים:

• setBackoffCriteria(JobInfo.BACKOFF_POLICY_EXPONENTIAL)
• setClipData()
• setEstimatedNetworkBytes()
• setMinimumNetworkChunkBytes()
• setPersisted()
• setNamespace()
• setRequiredNetwork()
• setRequiredNetworkType()
• setRequiresBatteryNotLow()
• setRequiresCharging()
• setRequiresStorageNotLow()

בדיקה

ברשימה הבאה מוצגים כמה שלבים לבדיקה ידנית של המשימות באפליקציה:

• כדי למצוא את מזהה המשימה, צריך להזין את הערך שהוגדר במשימה שנוצרת.

• כדי להריץ משימה באופן מיידי או כדי לנסות שוב משימה מסוימת, מריצים את הפקודה הבאה: הפקודה בחלון הטרמינל:

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

• כדי לדמות את עצירת המשימה בכוח המערכת (עקב תקינות המערכת או בתנאים שלא נכללים במכסה), מריצים את הפקודה הבאה בחלון הטרמינל:

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

למידע נוסף

• סקירה כללית על משימות ברקע
• אפשרויות למשימות ברקע של העברת נתונים

מקורות מידע נוספים

למידע נוסף על העברות נתונים שיזם המשתמש, אפשר לעיין במקורות המידע הנוספים הבאים:

• מחקר מקרה על שילוב של UIDT: ‏ שיפור של 10% במהימנות ההורדה במפות Google באמצעות API להעברת נתונים שהופעלה על ידי המשתמש