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

หากต้องการโอนข้อมูลที่อาจใช้เวลานาน คุณสามารถสร้างงาน 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 สำหรับการโอนข้อมูลด้วย ดังนี้

    class CustomTransferService : 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() ขณะสร้างงาน

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

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

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

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

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

คำแนะนำ

หากต้องการเรียกใช้งาน UIDT อย่างมีประสิทธิภาพ ให้ทำดังนี้

  1. กำหนดข้อจำกัดของเครือข่ายและข้อจำกัดในการดำเนินการของงานอย่างชัดเจนเพื่อระบุว่าควรดำเนินการงานเมื่อใด

  2. เรียกใช้งานแบบอะซิงโครนัสใน onStartJob() เช่น คุณสามารถทำได้โดยใช้ coroutine หากคุณไม่เรียกใช้งานแบบอะซิงโครนัส งานจะทำงานในเทรดหลักและอาจบล็อกเทรดดังกล่าว ซึ่งอาจทำให้เกิด ANR

  3. เพื่อหลีกเลี่ยงการเรียกใช้การดำเนินการนานเกินความจำเป็น ให้เรียกใช้ jobFinished() เมื่อการโอนเสร็จสิ้น ไม่ว่าจะสำเร็จหรือไม่ก็ตาม วิธีนี้จะช่วยให้งานไม่ทำงานนานเกินความจำเป็น หากต้องการดูสาเหตุที่งานหยุดทำงาน ให้ใช้เมธอด Callback 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)
}

หยุดงาน 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

ดูเพิ่มเติม

แหล่งข้อมูลเพิ่มเติม

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