กำหนดค่าแอป Wear OS สําหรับการส่ง Push หน้าปัด

การพุชหน้าปัดช่วยให้แอปจัดการหน้าปัดในอุปกรณ์ Wear OS ได้ ซึ่งรวมถึงการเพิ่ม อัปเดต และนำหน้าปัดออก รวมถึงการตั้งค่า หน้าปัดที่ใช้งานอยู่ กำหนดค่าแอป Wear OS ให้ ใช้ Watch Face Push API

ตั้งค่า

รวมการอ้างอิงที่จำเป็น

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

เพิ่มโค้ดต่อไปนี้ใน AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Required to use the Watch Face Push API.  -->
    <uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

    <!-- Required to be able to call the setWatchFaceAsActive() method. -->
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

</manifest>

รับการอ้างอิงไปยังอินสแตนซ์ของตัวจัดการ

รับอินสแตนซ์ของ WatchFacePushManager

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager ให้สิทธิ์เข้าถึงทุกวิธีในการโต้ตอบกับ Watch Face Push

ทำงานกับสล็อต

แนวคิดสำคัญเมื่อใช้ Watch Face Push คือช่อง สล็อตเป็นวิธี ระบุหน้าปัดที่ติดตั้งซึ่งเป็นของแอปพลิเคชันของคุณ ระบบ จะกำหนดจำนวนสูงสุดของสล็อตที่มาร์เก็ตเพลสมีได้ โดยใน Wear OS 6 ขีดจำกัดคือ 1

เมื่ออัปเดตหรือนำหน้าปัดออก ระบบจะใช้ slotId เพื่อระบุหน้าปัดที่จะดำเนินการ

แสดงหน้าปัด

หากต้องการแสดงชุดหน้าปัดที่ติดตั้ง ให้ใช้ listWatchFaces() ดังนี้

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

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

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

เพิ่มหน้าปัด

หากมีช่องโฆษณาว่างตามที่กำหนดโดยการตอบกลับ listWatchFaces ควรใช้วิธี addWatchFace() ดังนี้

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

อัปเดตหน้าปัด

การอัปเดตหน้าปัดช่วยให้คุณแทนที่เนื้อหาของช่องที่กำหนดด้วย แพ็กเกจใหม่ได้ ซึ่งอาจเป็นการอัปเกรดหน้าปัดเดียวกันเป็นเวอร์ชันที่ใหม่กว่า หรือเปลี่ยนหน้าปัดเป็นหน้าปัดอื่นทั้งหมด

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

นำหน้าปัดออก

วิธีนำหน้าปัดออก

// Remove the com.example.watchfacepush.green watch face.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

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

ตรวจสอบว่าหน้าปัดใช้งานอยู่หรือไม่

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

หากต้องการพิจารณาว่ามาร์เก็ตเพลสได้ตั้งค่าหน้าปัดที่ใช้งานอยู่หรือไม่ ให้ใช้ตรรกะต่อไปนี้

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

ระบุหน้าปัดเริ่มต้น

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

วิธีใช้ฟีเจอร์นี้

  1. ในการสร้างแอป Wear OS ให้รวมหน้าปัดเริ่มต้นไว้ในเส้นทางต่อไปนี้ assets/default_watchface.apk
  2. เพิ่มรายการต่อไปนี้ลงใน AndroidManifest.xml

    <application ...>
    <meta-data
        android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
        android:value="@string/default_wf_token" />
    

ตั้งค่าหน้าปัดที่ใช้งานอยู่

Watch Face Push เป็นวิธีให้แอปในมาร์เก็ตเพลสตั้งค่าหน้าปัดที่ใช้งานอยู่

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

การตั้งค่าหน้าปัดที่ใช้งานอยู่เป็นกระบวนการ 2 ขั้นตอน ดังนี้

  1. ขอสิทธิ์ Android ที่จำเป็นสำหรับการตั้งค่าหน้าปัดที่ใช้งานอยู่
  2. เรียกใช้เมธอด setWatchFaceAsActive

รับสิทธิ์เพื่อตั้งค่าหน้าปัดที่ใช้งานอยู่

สิทธิ์ที่จำเป็นคือ SET_PUSHED_WATCH_FACE_AS_ACTIVE ซึ่งต้อง เพิ่มลงในไฟล์ Manifest

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

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

ตั้งหน้าปัดเป็นหน้าปัดที่ใช้งานอยู่

เมื่อได้รับสิทธิ์แล้ว ให้เรียกใช้ setWatchFaceAsActive ในรหัสช่อง ของหน้าปัดที่ควรใช้งานอยู่

watchFacePushManager.setWatchFaceAsActive(slotId)

เมื่อใช้วิธีนี้แล้ว แอปโทรศัพท์ควรแสดงคำแนะนำเกี่ยวกับวิธีตั้งค่าหน้าปัดที่ใช้งานอยู่ด้วยตนเองแทน

อ่านข้อมูลเมตาเพิ่มเติมจาก APK ของหน้าปัดนาฬิกา

WatchFaceSlotออบเจ็กต์นี้ยังมีวิธีรับข้อมูลเพิ่มเติม ที่คุณประกาศในหน้าปัดได้ด้วย

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

  • ชื่อแพ็กเกจ: com.myapp.watchfacepush.mywatchface
  • เวอร์ชันแพ็กเกจ: 1.0.0

แต่หน้าปัดนี้อาจมาในรูปแบบ APK 4 แบบที่แตกต่างกัน ซึ่งทั้งหมดเกือบจะเหมือนกันทุกประการ แต่มีสีเริ่มต้นที่แตกต่างกัน ได้แก่ แดง เหลือง เขียว และน้ำเงิน ซึ่งตั้งค่าไว้ใน ColorConfiguration ใน XML ของ Watch Face Format

ความแตกต่างเล็กน้อยนี้จะแสดงใน APK ทั้ง 4 รายการ

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

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

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

ข้อควรพิจารณา

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

พาวเวอร์

ข้อควรพิจารณาที่สำคัญสำหรับแอปที่ทำงานบน Wear OS คือการใช้พลังงาน สำหรับ คอมโพเนนต์ Wear OS ของแอปในมาร์เก็ตเพลส ให้ทำดังนี้

  1. แอปของคุณควรทำงานให้น้อยและไม่บ่อยเท่าที่จะเป็นไปได้ (เว้นแต่ผู้ใช้จะโต้ตอบกับแอปโดยตรง) ซึ่งรวมถึง
    • ลดการปลุกแอปจากแอปโทรศัพท์
    • ลดการเรียกใช้งานของงาน WorkManager
  2. ตั้งเวลาการรายงานข้อมูลวิเคราะห์เมื่อนาฬิกากำลังชาร์จ
    1. หากต้องการรายงานสถิติการใช้งานจากแอป Wear OS หรือเมตริกอื่นๆ ให้ใช้ WorkManager ที่มีข้อจํากัด requiresCharging
  3. กำหนดเวลาอัปเดตเมื่อนาฬิกากำลังชาร์จและใช้ Wi-Fi
    1. คุณอาจต้องตรวจสอบเวอร์ชันของหน้าปัดที่ติดตั้งและ อัปเดตโดยอัตโนมัติ อีกครั้ง ให้ใช้ข้อจํากัด requiresCharging และประเภทเครือข่าย UNMETERED สําหรับ requiresNetworkType
    2. เมื่อชาร์จอยู่ อุปกรณ์มักจะมีสิทธิ์เข้าถึง Wi-Fi ขอใช้ Wi-Fi เพื่อดาวน์โหลด APK ที่อัปเดตแล้วอย่างรวดเร็ว และปล่อยเครือข่าย เมื่อเสร็จสิ้น
    3. คำแนะนำเดียวกันนี้ใช้ได้กับกรณีที่มาร์เก็ตเพลสอาจมีหน้าปัดนาฬิกาประจำวัน ให้ดาวน์โหลดล่วงหน้าขณะที่ชาร์จนาฬิกา
  4. อย่ากำหนดเวลางานเพื่อตรวจสอบหน้าปัดที่ใช้งานอยู่
    1. การตรวจสอบเป็นระยะๆ ว่ามาร์เก็ตเพลสยังมีหน้าปัดที่ใช้งานอยู่หรือไม่และเป็นหน้าปัดใดจะทำให้แบตเตอรี่หมดเร็ว โปรดหลีกเลี่ยงวิธีนี้
  5. อย่าใช้การแจ้งเตือนบนนาฬิกา
    1. หากแอปใช้การแจ้งเตือน ให้เน้นการแจ้งเตือนเหล่านี้ในโทรศัพท์ ซึ่งผู้ใช้ จะดำเนินการเพื่อเปิดแอปโทรศัพท์เพื่อดำเนินการต่อ ตรวจสอบว่าไม่ได้ เชื่อมต่อกับแอปนาฬิกาโดยใช้ setLocalOnly

กำลังแคช

ในตัวอย่างตลาดกลาง Canonical ระบบจะโอนหน้าปัดจากโทรศัพท์ ไปยังนาฬิกา โดยปกติแล้วการเชื่อมต่อนี้จะเป็นการเชื่อมต่อบลูทูธ ซึ่งอาจ ช้ามาก

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

ในกรณีที่ผู้ใช้ลองหน้าปัดอื่น แต่ตัดสินใจเปลี่ยนกลับไปใช้หน้าปัดที่เลือกไว้ก่อนหน้านี้ การดำเนินการนี้จะเกิดขึ้นแทบจะทันที

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

อัปเดตหน้าปัดที่มาพร้อมเครื่อง

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

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

หน้าปัดเริ่มต้นที่เป็นตัวแทน

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

ข้อควรพิจารณาบางประการเมื่อใช้หน้าปัดเริ่มต้นของนาฬิกา

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

    1. เพิ่มองค์ประกอบ Launch ลงในหน้าปัดเพื่อเปิดใช้ Intent โดยใช้แอป Wear OS เช่น

      <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

    2. ใน LaunchOnPhoneActivity ให้เปิดแอปโทรศัพท์โดยใช้ RemoteActivityHelper