ซิงค์รายการข้อมูลกับ Data Layer API

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

• เพย์โหลด: อาร์เรย์ไบต์ที่คุณตั้งค่าด้วยข้อมูลได้ ซึ่งช่วยให้คุณทำการซีเรียลไลซ์และ ดีซีเรียลไลซ์ออบเจ็กต์ได้เอง Payload มีขนาดไม่เกิน 100 KB
• เส้นทาง: สตริงที่ไม่ซ้ำกันซึ่งต้องขึ้นต้นด้วยเครื่องหมายทับ เช่น "/path/to/data".

หมายเหตุ: Data Layer API สามารถส่งข้อความและซิงค์ข้อมูลกับโทรศัพท์ Android หรือนาฬิกา Wear OS เท่านั้น หากอุปกรณ์ Wear OS จับคู่กับอุปกรณ์ iOS ไว้ Data Layer API จะไม่ ทำงาน

ด้วยเหตุนี้ โปรดอย่าใช้ Data Layer API เป็น วิธีหลักในการสื่อสารกับเครือข่าย แต่ให้ทำตาม รูปแบบเดียวกับแอปบนอุปกรณ์เคลื่อนที่ โดยมีข้อแตกต่างเล็กน้อย

โดยปกติแล้วคุณจะไม่ใช้ DataItem โดยตรง แต่จะทำดังนี้แทน

1. สร้างออบเจ็กต์ PutDataRequest โดยระบุเส้นทางสตริงเพื่อระบุรายการอย่างไม่ซ้ำกัน
2. เรียกใช้ setData() เพื่อตั้งค่า Payload
3. หากการซิงค์ล่าช้าจะส่งผลเสียต่อประสบการณ์ของผู้ใช้ ให้เรียกใช้ setUrgent()
4. ใช้วิธี putDataItem ของคลาส DataClient เพื่อขอให้ระบบสร้างรายการข้อมูล

เมื่อขอรายการข้อมูล ระบบจะแสดงออบเจ็กต์ที่ใช้ DataItem อินเทอร์เฟซอย่างเหมาะสม อย่างไรก็ตาม เราขอแนะนำให้คุณ ใช้ Data Map ซึ่งแสดงรายการข้อมูลด้วยอินเทอร์เฟซที่คล้ายกับ Bundle แทนการทำงานกับไบต์ดิบโดยใช้ setData()

ดูข้อมูลเพิ่มเติมได้ที่แอปตัวอย่าง DataLayer Sample

ซิงค์ข้อมูลกับ Data Map

ใช้คลาส DataMap เมื่อเป็นไปได้ วิธีนี้ช่วยให้คุณทำงานกับรายการข้อมูลในรูปแบบ Bundle ของ Android ได้ ดังนั้นระบบจะทำการซีเรียลไลซ์และดีซีเรียลไลซ์ออบเจ็กต์ให้คุณ และคุณสามารถจัดการข้อมูลด้วยคู่คีย์-ค่าได้

วิธีใช้ Data Map

1. สร้างออบเจ็กต์ PutDataMapRequest โดยตั้งค่าเส้นทางของรายการข้อมูล

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

2. เรียกใช้ PutDataMapRequest.getDataMap() เพื่อรับ Data Map ที่คุณ ตั้งค่าได้
3. ตั้งค่าสำหรับ Data Map โดยใช้วิธี put...() เช่น putString()
4. หากการซิงค์ล่าช้าจะส่งผลเสียต่อประสบการณ์ของผู้ใช้ ให้เรียกใช้ setUrgent().
5. เรียกใช้ PutDataMapRequest.asPutDataRequest() เพื่อรับออบเจ็กต์ PutDataRequest
6. ใช้วิธี putDataItem ของคลาส DataClient เพื่อขอให้ระบบสร้างรายการข้อมูล

   หมายเหตุ: หากอุปกรณ์พกพาและอุปกรณ์สวมใส่ไม่ได้เชื่อมต่อกัน ระบบจะบัฟเฟอร์ข้อมูลและซิงค์ข้อมูลเมื่อมีการเชื่อมต่ออีกครั้ง

วิธี increaseCounter() ในตัวอย่างต่อไปนี้แสดงวิธีสร้าง Data Map และใส่ข้อมูลลงใน Data Map

private fun increaseCounter(): Task<DataItem> {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    return Wearable.getDataClient(this)
        .putDataItem(putDataReq)
}
DataLayerActivity.kt

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการ Tasks ได้ใน เอกสารอ้างอิง

ข้อควรระวัง: ก่อนใช้ Wearable Data Layer API ให้ตรวจสอบว่า API พร้อมใช้งานในอุปกรณ์หรือไม่ หากไม่พร้อมใช้งาน ระบบจะแสดงข้อยกเว้น ใช้คลาส GoogleApiAvailability ตามที่ใช้งานใน Horologist

ตั้งค่าลำดับความสำคัญของ DataItem

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

หากคุณไม่เรียกใช้ setUrgent() ระบบอาจชะลอการซิงค์รายการข้อมูลที่ไม่เร่งด่วนนานถึง 30 นาที แม้ว่าโดยปกติแล้วการชะลอจะใช้เวลาเพียงไม่กี่นาที ความเร่งด่วนเริ่มต้นคือไม่เร่งด่วน ดังนั้นคุณต้องใช้ setUrgent() หากต้องการคงลักษณะการทำงานของการซิงค์ทันทีจาก API ของ Wear OS เวอร์ชันก่อนหน้า

รอรับเหตุการณ์รายการข้อมูล

หากฝั่งหนึ่งของการเชื่อมต่อ Data Layer เปลี่ยนรายการข้อมูล ให้แจ้งให้ผู้ใช้ทราบถึงการเปลี่ยนแปลงในอีกฝั่งของการเชื่อมต่อ คุณทำได้โดยใช้ Listener สำหรับเหตุการณ์รายการข้อมูล

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

override fun onDataChanged(dataEvents: DataEventBuffer) {

    dataEvents.forEach { event ->
        // DataItem changed
        if (event.type == DataEvent.TYPE_CHANGED) {
            event.dataItem.also { item ->
                if (item.uri.path?.compareTo("/count") == 0) {
                    DataMapItem.fromDataItem(item).dataMap.apply {
                        updateCount(getInt(COUNT_KEY))
                    }
                }
            }
        } else if (event.type == DataEvent.TYPE_DELETED) {
            // DataItem deleted
        }
    }
}
DataLayerActivity.kt

กิจกรรมนี้ใช้ DataClient.OnDataChangedListener อินเทอร์เฟซ กิจกรรมจะเพิ่มตัวเองเป็น Listener สำหรับเหตุการณ์รายการข้อมูลภายในวิธี onResume() และนำ Listener ออกในวิธี onPause() หากต้องการดูการใช้งานโดยใช้รูปภาพ, View Model และ บริการ โปรดดูแอปตัวอย่าง DataLayer

นอกจากนี้ คุณยังใช้ Listener เป็นบริการได้ด้วย ดูข้อมูลเพิ่มเติมได้ที่ รอรับเหตุการณ์ Data Layer events.