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

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ồ chính. Định cấu hình ứng dụng Wear OS để sử dụng Watch Face Push API.

Thiết lập

Thêm các phần phụ thuộc cần thiết:

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

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>

Tham chiếu đến phiên bản trình quản lý

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

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(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 Watch Face Push.

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

Một khái niệm quan trọng khi làm việc với Watch Face Push là các khe cắm. Vị trí 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 vị trí tối đa 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 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 dùng listWatchFaces():

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

Điều này giúp bạn xác định xem có sẵn vị trí hay không, hoặc liệu việc thêm một mặt đồng hồ khác có cần 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ó các khung giờ trống (theo 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.
}

Lưu ý: Đừng lưu trữ các giá trị slotId hoặc coi chúng là giá trị cố định. Trạng thái có thể thay đổi bên ngoài ứng dụng của bạn; ví dụ: người dùng có thể gỡ cài đặt mặt đồng hồ thông qua giao diện người dùng hệ thống. Luôn lấy trạng thái hiện tại ngay lập tức trước khi thực hiện bất kỳ thao tác nào dựa trên khe cắm.

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 khe cắm nhất định bằng một gói mới. Đây có thể là việc 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.
}

Lưu ý: Hãy cân nhắc xem ứng dụng của bạn có nên gọi removeWatchFace hay không. Thay vào đó, khi người dùng nhấn để gỡ cài đặt một mặt đồng hồ thông qua ứng dụng cửa hàng của bạn, bạn có thể muốn thay thế mặt đồng hồ đó bằng một mặt đồng hồ mặc định.

Điều này sẽ đảm bảo rằng mặt đồng hồ của bạn luôn có trong trình chọn mặt đồng hồ hệ thống, có thể làm nổi bật biểu trưng của bạn 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ó đang hoạt động hay không

Việc xác định xem trang web thương mại của bạn có đặt mặt đồng hồ đang hoạt động hay không là điều 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 muốn chọn một mặt đồng hồ khác, người dùng 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 để thay đổi này có hiệu lực. Tuy nhiên, nếu cửa hàng không đặt 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 về cách xử lý trải nghiệm người dùng này.

Để xác định xem cửa hàng có đặt mặt đồng hồ đang hoạt động hay không, hãy sử dụng logic sau:

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

Cảnh báo: Khi gọi updateWatchFace(), đừng gọi isWatchFaceActive() ngay sau đó vì điều này có thể dẫn đến kết quả không mong muốn. Có thể mất một chút thời gian để quá trình thay đổi mặt đồng hồ hoàn tất.

Thay vào đó, trước tiên, hãy xác định xem ứng dụng gọi có tham chiếu đến mặt đồng hồ đang hoạt động hay không, như minh hoạ trong đoạn mã trước, rồi sau đó gọi updateWatchFace(). Nếu updateWatchFace() hoàn tất thành công, bạn có thể giả định rằng ứng dụng của bạn vẫn kiểm soát mặt đồng hồ đang hoạt động.

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

Tính năng Đẩy mặt đồng hồ cho phép cài đặt một mặt đồng hồ mặc định khi ứng dụng trên trang web thương mại của bạn được cài đặt. Bản thân phương thức này không đặ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.

Cách dùng tính năng này:

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

2. Thêm mục 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" />
   

Lưu ý: Mẫu bản dựng điển hình bao gồm việc tạo default_watchface.apk như một phần của bản dựng ứng dụng tổng thể dưới dạng bước tiền xây dựng. Bạn có thể sử dụng cách này để điền giá trị tệp kê khai mã thông báo xác thực bằng cách yêu cầu quy trình tạo mặt đồng hồ mặc định xuất thêm một tệp XML tài nguyên Android và đưa đường dẫn tài nguyên đó vào làm đường dẫn tài nguyên bổ sung trong ứng dụng chính. Cách này đơn giản hơn so với việc cố gắng thao tác với chính tệp kê khai trong quá trình tạo bản dựng.

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

Watch Face Push cung cấp phương tiện để ứng dụng trên trang web thương mại đặt mặt đồng hồ đang hoạt động.

Điều này có nghĩa là ứng dụng có thể đặt mặt đồng hồ chính thành một mặt đồng hồ thuộc Marketplace trong trường hợp mặt đồng hồ chính hiện tại không thuộc Marketplace. Xin lưu ý rằng trong trường hợp cửa hàng đã 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 bằng cách gọi updateWatchFace để thay thế nội dung của khe cắm 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 2 giai đoạn:

1. Lấy Quyền Android cần thiết để đặt mặt đồng hồ chính.
2. Gọi phương thức setWatchFaceAsActive.

Có được quyền đặt mặt đồng hồ chính

Quyền bắt buộc là SET_PUSHED_WATCH_FACE_AS_ACTIVE và 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).

Lưu ý: Quyền này có số lần từ chối tối đa là 1: Nếu người dùng từ chối yêu cầu, thì bạn không thể đưa ra yêu cầu đó nữa. Trong trường hợp đó, ứng dụng sẽ chuyển người dùng đến phần cài đặt để điều chỉnh quyền theo cách thủ công.

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

Sau khi được cấp quyền, hãy gọi setWatchFaceAsActive trên mã nhận dạng vị trí của mặt đồng hồ cần kích hoạt:

watchFacePushManager.setWatchFaceAsActive(slotId)

Lưu ý: Bạn chỉ có thể đặt mặt đồng hồ đang hoạt động bằng cách này một lần. Nếu người dùng chuyển sang mặt đồng hồ của một nhà phát triển khác, thì việc gọi API này để đặt mặt đồng hồ đang hoạt động trở lại mặt đồng hồ của bạn sẽ gửi một ngoại lệ.

Sau khi sử dụng phương thức này, ứng dụng điện thoại của bạn nên hướng dẫn cách đặt mặt đồng hồ chính 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ể hữu ích, đặc biệt là 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 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ể có 4 tệp APK khác nhau, trong đó tất cả đều gần giống nhau, nhưng có màu mặc định khác nhau: đỏ, vàng, xanh lục và xanh dương, được đặt trong một ColorConfiguration trong XML Định dạng mặt đồng hồ.

Sự khác biệt nhỏ này sau đó được phản ánh trong từng tệp APK trong số 4 tệp APK:

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

Việc sử dụng một 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()

Lưu ý: Trong ví dụ trước, bạn cần cung cấp không gian tên cho thuộc tính vì none đã được khai báo trên thuộc tính. Nếu thuộc tính có dấu chấm (.), thì bạn không cần phải làm như vậy, vì vậy, bạn có thể truy xuất một thuộc tính có tên abc.def bằng cách sử dụng getMetaDataValues("abc.def").

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

Khi triển khai tính năng Đẩy mặt đồng hồ trong ứng dụng, bạn cần lưu ý một số điểm quan trọng, chẳng hạn như tập trung vào mức tiêu thụ điện năng, bộ nhớ đệm, cập nhật các mặt đồng hồ đi kèm và cung cấp một mặt đồng hồ mặc định mang tính đại diện.

Sức mạnh

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 là mức tiêu thụ điện năng. Đố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 càng ít và càng không thường xuyên càng tốt (trừ phi người dùng tương tác trực tiếp với ứng dụng). Trong đó có:
   • 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 tác vụ WorkManager
2. Lên lịch gửi báo cáo phân tích vào 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 ràng buộc requiresCharging.
3. Lên lịch cập nhật khi đồng hồ đang sạc và sử dụng Wi-Fi:
   1. Bạn có thể 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 chúng. Một lần nữa, hãy sử dụng ràng buộc requiresCharging và loại mạng UNMETERED cho requiresNetworkType.
   2. Khi đang sạc, thiết bị thường 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 và giải phóng mạng khi hoàn tất.
   3. Hướng dẫn này cũng áp dụng cho trường hợp nơi trang web thương mại có thể cung cấp mặt đồng hồ trong ngày; hãy tải mặt đồng hồ này xuống trước khi đồng hồ đang sạc.
4. Không lên lịch cho các công việc kiểm tra mặt đồng hồ đang hoạt động:
   1. Việc kiểm tra định kỳ 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ồ đó là mặt đồng hồ nào sẽ làm 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 những thông báo này trên điện thoại, nơi hành động của người dùng sẽ mở ứng dụng điện thoại để tiếp tục hành trình. Đảm bảo rằng những thành phần này không bắc cầu sang ứng dụng đồng hồ bằng cách dùng setLocalOnly.

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

Trong ví dụ chuẩn về trang web thương mại, 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, có thể khá chậm.

Để mang lại trải nghiệm người dùng tốt hơn và 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 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ư diễn ra ngay lập tức.

Tương tự, bạn có thể dùng yếu tố này để lưu trước vào bộ nhớ đệm cho mặt đồng hồ trong ngày hoặc các chương trình 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ên. Điều quan trọng cần lưu ý là mặc dù mặt đồng hồ này được cài đặt vào hệ thống khi ứng dụng của bạn được cài đặt trên trang web thương mại, 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 của bạn trên trang web thương mại.

Để xử lý tình huống này, ứng dụng của bạn trên trang web thương mại cần 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 trong số các tài sả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 của bạn: Mặt đồng hồ được cài đặt khi trang web 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 sử dụng mặt đồng hồ mặc định:

• Không dùng removeWatchFace nếu người dùng chọn gỡ cài đặt mộ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 cách dùng updateWatchFace. Việc 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.
• Thiết kế mặt đồng hồ mặc định đơn giản và dễ nhận biết ngay lập tức thông qua biểu trưng và chủ đề của bạ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 theo 2 giai đoạn:

  1. Thêm một 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 khởi chạy ứng dụng điện thoại bằng cách sử dụng RemoteActivityHelper.