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

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

• เพย์โหลด: อาร์เรย์ไบต์ที่คุณตั้งค่าด้วยข้อมูลได้ ซึ่งช่วยให้คุณทำการซีเรียลไลซ์และ ดีซีเรียลไลซ์ออบเจ็กต์ได้เอง ขนาดของเพย์โหลดจำกัดไว้ที่ 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() เพื่อตั้งค่าเพย์โหลด
3. หากการซิงค์ที่ล่าช้าจะส่งผลเสียต่อประสบการณ์ของผู้ใช้ ให้โทรหา setUrgent()
4. ใช้เมธอด putDataItem ของคลาส DataClient เพื่อขอให้ระบบสร้างรายการข้อมูล

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

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

ซิงค์ข้อมูลกับแผนที่ข้อมูล

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

วิธีใช้แผนที่ข้อมูล

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

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

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

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

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

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

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

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

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

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

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

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

หากการเชื่อมต่อชั้นข้อมูลด้านหนึ่งเปลี่ยนแปลงรายการข้อมูล ให้แจ้ง ผู้ใช้เกี่ยวกับการเปลี่ยนแปลงที่เกิดขึ้นในการเชื่อมต่ออีกด้าน ซึ่งทำได้โดยการติดตั้งใช้งาน 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() หากต้องการดูการติดตั้งใช้งานโดยใช้รูปภาพ โมเดล และ บริการ ให้ดูแอปตัวอย่าง DataLayer

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