Định cấu hình ứng dụng Wear OS cho tính năng đẩy mặt đồng hồ

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Watch Face Push cho phép ứng dụng của bạn quản lý mặt đồng hồ trên thiết bị Wear OS. Điều này bao gồm việc thêm, cập nhật và xoá mặt đồng hồ, cũng như đặt mặt đồng hồ đang hoạt động. Định cấu hình ứng dụng Wear OS để sử dụng API đẩy mặt đồng hồ.

Thiết lập

Bao gồm các phần phụ thuộc cần thiết:

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

Thêm nội dung sau vào 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>

Lấy tham chiếu đến thực thể trình quản lý

Lấy một thực thể của WatchFacePushManager:

val manager = WatchFacePushManager(context)

WatchFacePushManager cung cấp quyền truy cập vào tất cả các phương thức để tương tác với tính năng đẩy mặt đồng hồ.

Làm việc với các khe

Một khái niệm chính khi làm việc với tính năng đẩy mặt đồng hồ là khe. Khe là một cách để giải quyết các mặt đồng hồ đã cài đặt thuộc về ứng dụng của bạn. Hệ thống đặt số lượng tối đa của các vị trí mà một trang web thương mại có thể có; với Wear OS 6, giới hạn là 1.

Khi cập nhật hoặc xoá mặt đồng hồ, slotId được dùng để xác định mặt đồng hồ cần thực hiện thao tác.

Liệt kê mặt đồng hồ

Để liệt kê bộ mặt đồng hồ đã cài đặt, hãy sử dụng listWatchFaces():

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

Điều này cho phép bạn xác định xem có thể sử dụng vị trí này hay không hoặc việc thêm một mặt đồng hồ khác có yêu cầu thay thế mặt đồng hồ hiện có hay không. Danh sách này cũng cung cấp cho bạn thông tin chi tiết về mặt đồng hồ đã cài đặt. Ví dụ: để kiểm tra xem một gói mặt đồng hồ cụ thể đã được cài đặt hay chưa:

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

Thêm mặt đồng hồ

Nếu có sẵn các khung, như được xác định bằng phản hồi listWatchFaces, thì bạn nên sử dụng phương thức 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.
}

Cập nhật mặt đồng hồ

Việc cập nhật mặt đồng hồ cho phép bạn thay thế nội dung của một vị trí nhất định bằng một gói mới. Việc này có thể là nâng cấp cùng một mặt đồng hồ lên phiên bản mới hơn hoặc thay thế hoàn toàn mặt đồng hồ bằng một mặt đồng hồ khác.

// 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.
}

Xoá mặt đồng hồ

Cách xoá mặt đồng hồ:

// 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.
}

Điều này sẽ đảm bảo rằng mặt đồng hồ của bạn luôn xuất hiện trong bộ chọn mặt đồng hồ của hệ thống, có thể hiển thị biểu trưng của bạn một cách nổi bật và thậm chí có thể có một nút để chạy ứng dụng Marketplace trên điện thoại.

Kiểm tra xem mặt đồng hồ của bạn có đang hoạt động hay không

Việc xác định xem trang web thương mại của bạn đã đặt mặt đồng hồ đang hoạt động hay chưa là rất quan trọng để đảm bảo người dùng có trải nghiệm mượt mà: Nếu trang web thương mại đã đặt mặt đồng hồ đang hoạt động, thì nếu người dùng muốn chọn một mặt đồng hồ khác, họ chỉ cần thay thế mặt đồng hồ hiện tại thông qua ứng dụng trang web thương mại để mặt đồng hồ mới có hiệu lực. Tuy nhiên, nếu trang web thương mại không có bộ mặt đồng hồ đang hoạt động, thì ứng dụng điện thoại phải cung cấp thêm hướng dẫn cho người dùng. Hãy xem phần về ứng dụng điện thoại để biết thêm thông tin chi tiết về cách xử lý trải nghiệm người dùng này.

Cách xác định xem trang web thương mại có đặt mặt đồng hồ đang hoạt động hay không:

Cung cấp mặt đồng hồ mặc định

Watch Face Push cho phép cài đặt mặt đồng hồ mặc định khi ứng dụng trang web thương mại của bạn được cài đặt. Việc này không tự đặt mặt đồng hồ mặc định làm mặt đồng hồ đang hoạt động (xem phần đặt mặt đồng hồ đang hoạt động), nhưng sẽ đảm bảo rằng mặt đồng hồ của bạn có trong bộ chọn mặt đồng hồ của hệ thống.

Để dùng tính năng này:

1. Trong bản dựng ứng dụng Wear OS, hãy đưa mặt đồng hồ mặc định vào đường dẫn: assets/default_watchface.apk

2. Thêm mục nhập sau vào AndroidManifest.xml

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

Đặt mặt đồng hồ đang hoạt động

Tính năng đẩy mặt đồng hồ cung cấp phương tiện để ứng dụng trang web thương mại đặt mặt đồng hồ đang hoạt động.

Cụ thể, điều này có nghĩa là ứng dụng có thể đặt mặt đồng hồ đang hoạt động thành một mặt đồng hồ thuộc trang web thương mại trong trường hợp mặt đồng hồ đang hoạt động hiện tại không thuộc trang web thương mại. Xin lưu ý rằng trong trường hợp trang web thương mại đã có mặt đồng hồ đang hoạt động, bạn có thể thay đổi mặt đồng hồ này thành một mặt đồng hồ khác thông qua lệnh gọi đến updateWatchFace để thay thế nội dung của vị trí mặt đồng hồ bằng một mặt đồng hồ khác.

Việc thiết lập mặt đồng hồ đang hoạt động là một quy trình gồm hai giai đoạn:

1. Nhận Quyền trên Android cần thiết để đặt mặt đồng hồ đang hoạt động.
2. Gọi phương thức setWatchFaceAsActive.

Lấy quyền để đặt mặt đồng hồ đang hoạt động

Quyền bắt buộc là SET_PUSHED_WATCH_FACE_AS_ACTIVE, bạn phải thêm quyền này vào tệp kê khai:

<?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>

Vì đây là quyền khi bắt đầu chạy, nên ứng dụng của bạn phải yêu cầu người dùng cấp quyền này khi ứng dụng chạy (hãy cân nhắc sử dụng thư viện Accompanist để hỗ trợ việc này).

Đặt mặt đồng hồ làm mặt đồng hồ chính

Sau khi cấp quyền, hãy gọi setWatchFaceAsActive trên mã khe của mặt đồng hồ sẽ hoạt động:

watchFacePushManager.setWatchFaceAsActive(slotId)

Sau khi bạn sử dụng phương thức này, ứng dụng điện thoại sẽ cung cấp hướng dẫn về cách đặt mặt đồng hồ đang hoạt động theo cách thủ công.

Đọc siêu dữ liệu bổ sung từ tệp APK mặt đồng hồ

Đối tượng WatchFaceSlot cũng cung cấp phương tiện để lấy thêm thông tin mà bạn có thể khai báo trên mặt đồng hồ.

Điều này có thể đặc biệt hữu ích trong các trường hợp bạn có các biến thể nhỏ của cùng một mặt đồng hồ. Ví dụ: bạn có thể xác định mặt đồng hồ:

• Tên gói: com.myapp.watchfacepush.mywatchface
• Phiên bản gói: 1.0.0

Tuy nhiên, mặt đồng hồ này có thể xuất hiện dưới dạng 4 tệp APK khác nhau, trong đó tất cả đều gần như giống hệt nhau, nhưng có màu mặc định khác nhau: đỏ, vàng, xanh lục và xanh dương, được đặt trong ColorConfiguration trong tệp XML Định dạng mặt đồng hồ.

Sau đó, sự khác biệt nhỏ này được phản ánh trong mỗi tệp APK:

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

Việc sử dụng thuộc tính tuỳ chỉnh cho phép ứng dụng của bạn xác định biến thể nào trong số này được cài đặt:

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

Những yếu tố nên cân nhắc

Những điểm quan trọng cần cân nhắc khi triển khai tính năng Đẩy mặt đồng hồ trong ứng dụng của bạn bao gồm tập trung vào mức tiêu thụ điện năng, lưu vào bộ nhớ đệm, cập nhật mặt đồng hồ đi kèm và cung cấp mặt đồng hồ mặc định đại diện.

Sức mạnh

Mức tiêu thụ điện năng là một yếu tố quan trọng cần cân nhắc đối với mọi ứng dụng chạy trên Wear OS. Đối với thành phần Wear OS của ứng dụng trên trang web thương mại:

1. Ứng dụng của bạn nên chạy ít và ít thường xuyên nhất có thể (trừ khi người dùng tương tác trực tiếp với ứng dụng). Bao gồm:
   • Giảm thiểu việc đánh thức ứng dụng từ ứng dụng điện thoại
   • Giảm thiểu việc chạy các công việc WorkManager
2. Lên lịch báo cáo số liệu phân tích cho thời điểm đồng hồ đang sạc:
   1. Nếu bạn muốn báo cáo số liệu thống kê về mức sử dụng từ ứng dụng Wear OS hoặc bất kỳ chỉ số nào khác, hãy sử dụng WorkManager với quy tắc ràng buộc requiresCharging.
3. Lên lịch cập nhật khi đồng hồ đang sạc và sử dụng WiFi:
   1. Bạn nên kiểm tra phiên bản của các mặt đồng hồ đã cài đặt và tự động cập nhật các mặt đồng hồ đó. Một lần nữa, hãy sử dụng quy tắc ràng buộc requiresCharging và loại mạng UNMETERED cho requiresNetworkType.
   2. Khi đang sạc, thiết bị có thể có quyền truy cập vào Wi-Fi. Yêu cầu Wi-Fi để tải nhanh các tệp APK đã cập nhật xuống và giải phóng mạng khi hoàn tất.
   3. Hướng dẫn tương tự cũng áp dụng cho trường hợp trang web thương mại có thể cung cấp mặt đồng hồ của ngày; hãy tải trước mặt đồng hồ này xuống trong khi đồng hồ đang sạc.
4. Không lên lịch công việc để kiểm tra mặt đồng hồ đang hoạt động:
   1. Định kỳ kiểm tra xem trang web thương mại của bạn có còn mặt đồng hồ đang hoạt động hay không và mặt đồng hồ nào đang tiêu hao pin. Tránh sử dụng phương pháp này.
5. Không sử dụng thông báo trên đồng hồ:
   1. Nếu ứng dụng của bạn sử dụng thông báo, hãy tập trung vào thông báo trên điện thoại, nơi hành động của người dùng mở ứng dụng điện thoại để tiếp tục hành trình. Đảm bảo các ứng dụng này không chuyển sang ứng dụng đồng hồ bằng setLocalOnly.

Chức năng lưu vào bộ nhớ đệm

Trong ví dụ về trang web thương mại chuẩn, mặt đồng hồ được chuyển từ điện thoại sang đồng hồ. Kết nối này thường là kết nối Bluetooth và có thể khá chậm.

Để vừa mang lại trải nghiệm tốt hơn cho người dùng vừa tiết kiệm năng lượng truyền lại, hãy cân nhắc triển khai một bộ nhớ đệm nhỏ trong thiết bị Wear OS để lưu trữ một số tệp APK.

Trong trường hợp người dùng thử một mặt đồng hồ khác nhưng sau đó quyết định quay lại mặt đồng hồ đã chọn trước đó, thì thao tác này gần như tức thì.

Tương tự, bạn có thể dùng tính năng này để lưu vào bộ nhớ đệm trước cho mặt đồng hồ trong ngày hoặc các giao thức tương tự, trong đó mặt đồng hồ được tải xuống trong khi thiết bị Wear OS đang sạc.

Cập nhật mặt đồng hồ đi kèm

Ứng dụng của bạn có thể bao gồm một thành phần mặt đồng hồ mặc định như mô tả trước đó. Điều quan trọng là bạn phải nhận ra rằng mặc dù mặt đồng hồ này được cài đặt vào hệ thống khi ứng dụng trang web thương mại được cài đặt, nhưng mặt đồng hồ sẽ không được cập nhật nếu phiên bản mới hơn được đi kèm với bất kỳ bản cập nhật nào cho ứng dụng trang web thương mại.

Để xử lý trường hợp này, ứng dụng trang web thương mại của bạn phải theo dõi thao tác truyền tin MY_PACKAGE_REPLACED và kiểm tra xem có cần cập nhật mặt đồng hồ nào được đóng gói từ các thành phần gói hay không.

Mặt đồng hồ mặc định tiêu biểu

Mặt đồng hồ mặc định là một cách hay để giúp người dùng khám phá và sử dụng trang web thương mại của bạn: Mặt đồng hồ được cài đặt khi trang web thương mại của bạn được cài đặt, vì vậy, người dùng có thể tìm thấy mặt đồng hồ đó trong thư viện mặt đồng hồ.

Một số điều cần cân nhắc khi làm việc với mặt đồng hồ mặc định:

• Đừng sử dụng removeWatchFace nếu người dùng chọn gỡ cài đặt mặt đồng hồ khỏi ứng dụng trang web thương mại của bạn. Thay vào đó, trong trường hợp này, hãy chuyển mặt đồng hồ về mặt đồng hồ mặc định bằng updateWatchFace. Điều này giúp người dùng tìm thấy mặt đồng hồ của bạn và thiết lập mặt đồng hồ đó trong thư viện.
• Làm cho mặt đồng hồ mặc định trở nên đơn giản và dễ nhận biết ngay lập tức thông qua biểu trưng và giao diện. Điều này giúp người dùng tìm thấy mặt đồng hồ trong thư viện mặt đồng hồ.

• Thêm một nút vào mặt đồng hồ mặc định để mở ứng dụng điện thoại. Bạn có thể thực hiện việc này trong hai giai đoạn:

  1. Thêm phần tử Launch vào mặt đồng hồ để chạy một ý định bằng ứng dụng Wear OS, ví dụ:

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

  2. Trong LaunchOnPhoneActivity, hãy chạy ứng dụng điện thoại bằng RemoteActivityHelper.