การโอนข้อมูลที่เริ่มต้นโดยผู้ใช้

หากต้องการโอนข้อมูลที่อาจใช้เวลานาน คุณสามารถสร้างงาน JobScheduler และระบุว่าเป็นงานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ (UIDT) งาน UIDT มีไว้สำหรับการโอนข้อมูลระยะยาว ซึ่งเริ่มต้นโดยผู้ใช้อุปกรณ์ เช่น การดาวน์โหลดไฟล์จากเซิร์ฟเวอร์ระยะไกล งาน UIDT เปิดตัวพร้อม Android 14 (API ระดับ 34)

งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้จะเริ่มโดยผู้ใช้ งานเหล่านี้ต้องมีการแจ้งเตือน เริ่มต้นทันที และอาจทำงานได้เป็นระยะเวลานานตามที่เงื่อนไขของระบบอนุญาต คุณเรียกใช้งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้หลายงานพร้อมกันได้

ต้องกำหนดเวลางานที่ผู้ใช้เริ่มในขณะที่แอปพลิเคชันแสดงต่อผู้ใช้ (หรือในเงื่อนไขที่อนุญาตอย่างใดอย่างหนึ่ง) หลังจากเป็นไปตามข้อจำกัดทั้งหมดแล้ว ระบบปฏิบัติการจะเรียกใช้การทำงานที่ผู้ใช้เริ่มได้ โดยขึ้นอยู่กับข้อจำกัดด้าน สถานะของระบบ นอกจากนี้ ระบบยังอาจใช้ขนาดเพย์โหลดโดยประมาณที่ระบุเพื่อ พิจารณาระยะเวลาที่งานจะดำเนินการ

ตั้งเวลางานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้

หากต้องการเรียกใช้งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ ให้ทำดังนี้

1. ตรวจสอบว่าแอปได้ประกาศ JobService และสิทธิ์ที่เกี่ยวข้องในไฟล์ Manifest

   <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

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

3. เรียกใช้เมธอด 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)
           // ...
           .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, DownloadTransferService.class))
       // ...
       .setUserInitiated(true)
       .setRequiredNetwork(networkRequest)
       // Provide your estimate of the network traffic here
       .setEstimatedNetworkBytes(1024 * 1024 * 1024)
       // ...
       .build();

4. ขณะที่งานกำลังดำเนินการ ให้เรียกใช้ setNotification() ในออบเจ็กต์ JobService การเรียกใช้ setNotification()จะทำให้ผู้ใช้ทราบว่างานกำลังทำงานอยู่ ทั้งใน ตัวจัดการงานและในพื้นที่การแจ้งเตือนของแถบสถานะ

   เมื่อการดำเนินการเสร็จสมบูรณ์แล้ว ให้เรียกใช้ jobFinished() เพื่อส่งสัญญาณไปยังระบบ ว่างานเสร็จสมบูรณ์แล้ว หรือควรจัดกำหนดเวลางานใหม่

   Kotlin

   class DownloadTransferService: 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 DownloadTransferService 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() เช่น คุณทำได้โดยใช้โครูทีน หากคุณไม่เรียกใช้ Task แบบไม่พร้อมกัน งานจะทำงานในเทรดหลักและอาจบล็อกเทรดหลัก ซึ่งอาจทำให้เกิด ANR

3. หากต้องการหลีกเลี่ยงการเรียกใช้งานนานกว่าที่จำเป็น ให้เรียกใช้ jobFinished() เมื่อการโอนเสร็จสิ้น ไม่ว่าจะสำเร็จหรือล้มเหลว วิธีนี้จะช่วยให้งานไม่ต้องทำงานนานเกินความจำเป็น หากต้องการทราบสาเหตุที่งานหยุดทำงาน ให้ใช้เมธอดเรียกกลับ onStopJob() และเรียก JobParameters.getStopReason()

ความเข้ากันได้แบบย้อนหลัง

ขณะนี้ยังไม่มีไลบรารี Jetpack ที่รองรับงาน UIDT ด้วยเหตุนี้ เราขอแนะนำให้คุณควบคุมการเปลี่ยนแปลงด้วยโค้ดที่ยืนยันว่าคุณ ใช้ Android 14 ขึ้นไป ใน Android เวอร์ชันที่ต่ำกว่า คุณสามารถใช้การติดตั้งใช้งานบริการที่ทำงานอยู่เบื้องหน้าของ WorkManager เป็นแนวทางสำรองได้

ต่อไปนี้เป็นตัวอย่างโค้ดที่ตรวจสอบเวอร์ชันระบบที่เหมาะสม

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

ทั้งผู้ใช้และระบบสามารถหยุดงานการโอนที่ผู้ใช้เริ่มได้

โดยผู้ใช้จากตัวจัดการงาน

ผู้ใช้สามารถหยุดงานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ซึ่งปรากฏในตัวจัดการงานได้

ขณะผู้ใช้กดหยุด ระบบจะทำดังนี้

• สิ้นสุดกระบวนการของแอปทันที รวมถึงงานหรือบริการอื่นๆ ทั้งหมดที่ทำงานอยู่เบื้องหน้า
• ไม่เรียกใช้ onStopJob() สำหรับงานที่ทำงานอยู่
• ป้องกันไม่ให้กำหนดเวลางานซึ่งผู้ใช้มองเห็นใหม่

ด้วยเหตุนี้ เราจึงขอแนะนำให้ระบุการควบคุมในการแจ้งเตือนที่โพสต์สำหรับงานเพื่อให้หยุดงานและกำหนดเวลาใหม่ได้อย่างราบรื่น

โปรดทราบว่าในบางกรณี ปุ่มหยุดจะไม่ปรากฏข้างงานใน Task Manager หรืองานจะไม่แสดงใน Task Manager เลย

โดยระบบ

งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้จะไม่ได้รับผลกระทบจากโควต้า App Standby Buckets ซึ่งแตกต่างจากงานปกติ อย่างไรก็ตาม ระบบจะยังคงหยุดงานหากมีเงื่อนไขต่อไปนี้เกิดขึ้น

• ไม่เป็นไปตามข้อจำกัดที่นักพัฒนาแอปกำหนดอีกต่อไป
• ระบบพิจารณาว่างานทำงานนานเกินความจำเป็นในการ ดำเนินงานการโอนข้อมูลให้เสร็จสมบูรณ์
• ระบบต้องให้ความสำคัญกับสถานะของระบบและหยุดงานเนื่องจากสถานะความร้อนเพิ่มขึ้น
• ระบบจะปิดกระบวนการของแอปเนื่องจากหน่วยความจำของอุปกรณ์เหลือน้อย

เมื่อระบบหยุดงานเนื่องจากเหตุผลอื่นๆ นอกเหนือจากหน่วยความจำของอุปกรณ์เหลือน้อย ระบบจะเรียกใช้ onStopJob() และระบบจะลองทำงานอีกครั้งในเวลาที่ระบบเห็นว่าเหมาะสมที่สุด ตรวจสอบว่าแอปสามารถรักษาสถานะการโอนข้อมูลได้แม้ว่าจะไม่ได้เรียกใช้ onStopJob() และแอปสามารถกู้คืนสถานะนี้ได้เมื่อมีการเรียกใช้ onStartJob() อีกครั้ง

เงื่อนไขที่อนุญาตสำหรับการตั้งเวลางานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้

แอปจะเริ่มงานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ได้ก็ต่อเมื่อแอปอยู่ในกรอบเวลาที่เห็นได้ หรือเมื่อเป็นไปตามเงื่อนไขบางอย่างต่อไปนี้

• หากแอปเปิดกิจกรรมจากเบื้องหลังได้ ก็จะเปิดงานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้จากเบื้องหลังได้เช่นกัน
• หากแอปมีกิจกรรมในกองซ้อนด้านหลังของงานที่มีอยู่บนหน้าจอล่าสุด ก็ไม่ได้หมายความว่างานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้จะทำงานได้

หากกำหนดเวลาให้งานทำงานในช่วงเวลาที่ไม่เป็นไปตามเงื่อนไขที่จำเป็น งานจะดำเนินการไม่สำเร็จและแสดงรหัสข้อผิดพลาด 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: Google Maps ปรับปรุงความน่าเชื่อถือในการดาวน์โหลดได้ 10% โดยใช้ User Initiated Data Transfer API