Konfigurowanie aplikacji na Wear OS na potrzeby przesyłania tarczy zegarka

Push tarczy zegarka umożliwia zarządzanie tarczami zegarka na urządzeniu z Wear OS. Dotyczy to dodawania, aktualizowania i usuwania tarcz zegarka oraz ustawiania aktywnej tarczy zegarka. Skonfiguruj aplikację na Wear OS, aby używała interfejsu Watch Face Push API.

Skonfiguruj

Dodaj niezbędne zależności:

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

Dodaj do pliku AndroidManifest.xml te informacje:

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

Pobieranie odwołania do instancji menedżera

Uzyskaj instancję WatchFacePushManager:

val manager = WatchFacePushManager(context)

WatchFacePushManager zapewnia dostęp do wszystkich metod interakcji z pushem tarczy zegarka.

Praca z przedziałami

Kluczowym pojęciem podczas pracy z Push tarczy zegarka są miejsca. Slots to sposób adresowania zainstalowanych tarcz zegarka należących do Twojej aplikacji. System określa maksymalną liczbę slotów, które może mieć platforma handlowa. W Wear OS 6 limit wynosi 1.

Podczas aktualizowania lub usuwania tarczy zegarka slotId służy do identyfikacji tarczy, na której ma zostać wykonana dana operacja.

Lista tarcz zegarka

Aby wyświetlić listę zainstalowanych tarcz zegarka, użyj listWatchFaces():

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

Dzięki temu możesz określić, czy slot jest dostępny, czy dodanie kolejnej tarczy wymaga zastąpienia obecnej. Na liście znajdziesz też szczegółowe informacje o zainstalowanej tarczy zegarka. Aby na przykład sprawdzić, czy dany pakiet tarczy zegarka jest zainstalowany:

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

Dodawanie tarczy zegarka

Jeśli są dostępne sloty, co określa odpowiedź listWatchFaces, należy użyć metody 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.
}

Aktualizowanie tarczy zegarka

Aktualizacja tarczy zegarka umożliwia zastąpienie zawartości danego slotu nowym pakietem. Może to być uaktualnienie tej samej tarczy zegarka do nowszej wersji lub całkowite zastąpienie jej inną.

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

Usuwanie tarczy zegarka

Aby usunąć tarczę zegarka:

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

Dzięki temu tarcza zegarka będzie zawsze widoczna w systemowym selektorze tarcz, będzie zawierać Twoje logo i może nawet mieć przycisk uruchamiający aplikację z Marketplace na telefonie.

Sprawdzanie, czy tarcza zegarka jest aktywna

Określenie, czy na Twoim rynku jest aktywna tarcza zegarka, jest ważne dla zapewnienia użytkownikowi płynnego korzystania z aplikacji: jeśli na rynku jest już aktywna tarcza zegarka, a użytkownik chce wybrać inną, wystarczy, że za pomocą aplikacji na rynku zastąpi obecną tarczę. Jeśli jednak na platformie nie ma aktywnej tarczy zegarka, aplikacja na telefon musi wyświetlić użytkownikowi więcej wskazówek. Więcej informacji o tym, jak obsługiwać tę funkcję, znajdziesz w sekcji dotyczącej aplikacji na telefon.

Aby sprawdzić, czy na platformie jest ustawiona aktywna tarcza zegarka:

Dostarczanie domyślnej tarczy zegarka

Push tarczy zegarka umożliwia zainstalowanie domyślnej tarczy zegarka po zainstalowaniu aplikacji sklepu. Nie spowoduje to automatycznie ustawienia domyślnej tarczy zegarka jako aktywnej (patrz ustawienie aktywnej tarczy zegarka), ale zapewni, że tarcza zegarka będzie dostępna w systemowym selektorze tarcz.

Aby korzystać z tej funkcji:

  1. W kompilacji aplikacji na Wear OS uwzględnij domyślną tarczę zegarka w ścieżce:assets/default_watchface.apk

  2. Dodaj do pliku AndroidManifest.xml ten wpis:

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

Ustawianie aktywnej tarczy zegarka

Push tarczy zegarka umożliwia aplikacji na platformie ustawienie aktywnej tarczy zegarka.

Oznacza to, że aplikacja może ustawić aktywną tarczę zegarka jako należącą do Marketplace w przypadku, gdy bieżąca aktywna tarcza zegarka nie należy do Marketplace. Pamiętaj, że jeśli na platformie handlowej jest już aktywna tarcza zegarka, zmiana na inną tarczę zegarka odbywa się za pomocą wywołania funkcji updateWatchFace, która zastępuje zawartość slotu tarczy zegarka inną tarczą zegarka.

Ustawienie aktywnej tarczy zegarka odbywa się w 2 etapach:

  1. Uzyskaj uprawnienia Androida wymagane do ustawienia aktywnej tarczy zegarka.
  2. Wywołaj metodę setWatchFaceAsActive.

Uzyskiwanie uprawnień do ustawiania aktywnej tarczy zegarka

Wymagane uprawnienie to SET_PUSHED_WATCH_FACE_AS_ACTIVE, które musi zostać dodane do pliku manifestu:

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

Ponieważ jest to uprawnienie w czasie działania, aplikacja musi poprosić użytkownika o to uprawnienie, gdy jest uruchomiona (w tym celu możesz użyć biblioteki Accompanist).

Ustaw tarczę zegarka jako aktywną

Po udzieleniu uprawnień wywołaj funkcję setWatchFaceAsActive z identyfikatorem slotu tarczy zegara, który ma być aktywny:

watchFacePushManager.setWatchFaceAsActive(slotId)

Gdy to zrobisz, aplikacja na telefonie powinna wyświetlić instrukcje ręcznego ustawiania aktywnej tarczy zegarka.

odczytywać dodatkowe metadane z pliku APK tarczy zegarka;

Obiekt WatchFaceSlot umożliwia też uzyskanie dodatkowych informacji, które możesz zadeklarować na tarczy zegarka.

Może to być przydatne zwłaszcza w sytuacjach, gdy masz niewielkie warianty tego samego tarczy zegarka. Możesz na przykład zdefiniować tarczę zegarka:

  • Nazwa pakietu: com.myapp.watchfacepush.mywatchface
  • Wersja pakietu: 1.0.0

Tarcza zegarka może jednak występować w 4 różnych pakietach APK, które są prawie identyczne, ale mają różne domyślne kolory: czerwony, żółty, zielony i niebieski, ustawione w pliku ColorConfiguration w pliku XML Formatu tarczy zegarka.

Ta niewielka różnica jest następnie odzwierciedlana w 4 plikach APK:

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

Korzystanie z właściwości niestandardowej pozwala aplikacji określić, która z tych wersji jest zainstalowana:

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

co należy wziąć pod uwagę

Ważne kwestie, o których należy pamiętać podczas implementowania w aplikacji przesyłania tarczy zegarka, to m.in. zużycie energii, buforowanie, aktualizowanie dołączonych tarcz zegarka i udostępnianie reprezentatywnej domyślnej tarczy zegarka.

Moc

W przypadku każdej aplikacji na Wear OS kluczowym czynnikiem jest zużycie energii. W przypadku komponentu Wear OS aplikacji z Marketplace:

  1. Aplikacja powinna działać jak najrzadziej i jak najkrócej (chyba że użytkownik bezpośrednio z nią współdziała). Dotyczy to m.in.:
    • Minimalizowanie uruchamiania aplikacji z aplikacji Telefon
    • Minimalizowanie uruchomionych zadań WorkManager
  2. Zaplanuj generowanie raportów statystycznych na czas ładowania zegarka:
    1. Jeśli chcesz raportować statystyki użytkowania z aplikacji na Wear OS lub z innych danych pomiarowych, użyj WorkManagera z ograniczeniem requiresCharging.
  3. Zaplanuj aktualizacje na czas ładowania zegarka i użyj Wi-Fi:
    1. Możesz sprawdzić wersje zainstalowanych tarcz zegarka i zaktualizować je automatycznie. Ponownie użyj ograniczenia requiresCharging i typu sieci UNMETERED dla requiresNetworkType.
    2. Podczas ładowania urządzenie ma prawdopodobnie dostęp do Wi-Fi. Poproś o Wi-Fi, aby szybko pobrać zaktualizowane pliki APK, a potem zwolnij sieć.
    3. Te same wskazówki dotyczą sytuacji, gdy na platformie dostępne jest tarczę dnia. Pobierz ją z góry, gdy zegarek się ładuje.
  4. Nie planuj zadań sprawdzających aktywną tarczę zegarka:
    1. Okresowe sprawdzanie, czy na Twoim rynku nadal jest aktywna tarcza zegarka i która to tarcza, powoduje zużycie baterii. Unikaj takiego podejścia.
  5. Nie używaj powiadomień na zegarku:
    1. Jeśli Twoja aplikacja korzysta z powiadomień, skup się na telefonie, gdzie działanie użytkownika powoduje otwarcie aplikacji na telefonie, aby kontynuować. Upewnij się, że nie są one udostępniane aplikacji na zegarku za pomocą funkcji setLocalOnly.

Buforowanie

W przykładzie kanonicznej platformy Marketplace tarcze zegara są przenoszone z telefonu na zegarek. Jest to zwykle połączenie Bluetooth, które może być dość powolne.

Aby zapewnić lepsze wrażenia użytkownika i zaoszczędzić energię na retransmisję, rozważ wdrożenie małego poziomu pamięci podręcznej na urządzeniu z Wear OS, aby przechowywać kilka plików APK.

Jeśli użytkownik spróbuje ustawić inną tarczę zegarka, ale zdecyduje się wrócić do wcześniej wybranej tarczy, ta czynność zostanie wykonana niemal natychmiast.

Można go też używać do wstępnego przechowywania tarczy dnia lub podobnych schematów, w których tarcze są pobierane podczas ładowania urządzenia z Wear OS.

Aktualizowanie dołączonych tarcz zegarka

Aplikacja może zawierać domyślny zasób tarczy zegarka, jak opisano wcześniej. Pamiętaj, że chociaż ta tarcza jest zainstalowana w systemie, gdy aplikacja Marketplace jest zainstalowana, nie jest aktualizowana, jeśli nowsza wersja jest dołączona do aktualizacji aplikacji Marketplace.

Aby obsłużyć tę sytuację, aplikacja na platformie powinna nasłuchiwać działania MY_PACKAGE_REPLACED i sprawdzać, czy trzeba zaktualizować dowolną z dołączonych tarcz zegarków z zasobami pakietu.

Przykładowa domyślna tarcza zegarka

Domyślna tarcza zegarka to świetny sposób na to, aby użytkownicy mogli znaleźć i korzystać z Twojego marketplace: gdy zainstalujesz marketplace, tarcza zegarka jest automatycznie instalowana, więc użytkownicy mogą ją znaleźć w galerii tarcz.

Uwagi dotyczące pracy z domyślnymi tarczami zegarka:

  • Nie używaj polecenia removeWatchFace, jeśli użytkownik zdecyduje się odinstalować tarczę zegarka z aplikacji na platformie. W takim przypadku przywróć domyślną tarczę zegarka za pomocą polecenia updateWatchFace. Pomaga to użytkownikom znaleźć tarczę zegarka i ustawić ją z galerii.
  • Upewnij się, że domyślna tarcza zegarka jest prosta i natychmiast rozpoznawalna dzięki Twojemu logo i motywowi. Dzięki temu użytkownicy łatwiej znajdą tarczę w galerii tarcz zegarka.

  • Dodaj przycisk na domyślnej tarczy zegarka, aby otworzyć aplikację na telefonie. Można to zrobić na 2 sposoby:

    1. Dodaj element Launch do tarczy zegarka, aby uruchomić intencję za pomocą aplikacji Wear OS, na przykład:

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

    2. W LaunchOnPhoneActivity otwórz aplikację Telefon RemoteActivityHelper.