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

Funkcja Watch Face Push umożliwia aplikacji zarządzanie tarczami zegarka na urządzeniu z Wear OS. Obejmuje to dodawanie, aktualizowanie i usuwanie tarcz zegarka, a także ustawianie aktywnej tarczy zegarka. Skonfiguruj aplikację na Wear OS, aby korzystała z interfejsu Watch Face Push API.

Konfiguracja

Dodaj niezbędne zależności:

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

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>

Uzyskiwanie odwołania do instancji menedżera

Uzyskaj instancję WatchFacePushManager:

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager zapewnia dostęp do wszystkich metod interakcji z funkcją przesyłania tarcz zegara.

Praca z przedziałami

Kluczowym pojęciem podczas pracy z funkcją przesyłania tarcz zegarka są miejsca. Gniazda to sposób odwoływania się do zainstalowanych tarcz zegarka, które należą do Twojej aplikacji. System określa maksymalną liczbę miejsc, które może mieć platforma handlowa. W przypadku Wear OS 6 limit wynosi 1.

Podczas aktualizowania lub usuwania tarczy zegarka element slotId służy do identyfikowania tarczy, na której ma zostać wykonana 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 sprawdzić, czy gniazdo jest dostępne, czy dodanie kolejnej tarczy zegarka wymaga zastąpienia istniejącej. Lista zawiera też szczegółowe informacje o zainstalowanej tarczy zegarka. Aby na przykład sprawdzić, czy dany pakiet tarczy zegara jest zainstalowany:

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

Dodawanie tarczy zegarka

Jeśli są dostępne boksy (co wynika z odpowiedzi 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.
}

Uwaga: nie przechowuj wartości slotId ani nie traktuj ich jako trwałych. Stan może się zmienić poza aplikacją. Na przykład użytkownik może odinstalować tarczę zegarka za pomocą interfejsu systemu. Zawsze natychmiast pobieraj bieżący stan przed wykonaniem dowolnej operacji opartej na przedziałach czasu.

Aktualizowanie tarczy zegarka

Aktualizacja tarczy zegara umożliwia zastąpienie zawartości danego miejsca nowym pakietem. Może to być aktualizacja 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.
}

Uwaga: zastanów się, czy Twoja aplikacja powinna w ogóle wywoływać funkcję removeWatchFace. Zamiast tego, gdy użytkownik kliknie, aby odinstalować tarczę zegarka w aplikacji na platformie handlowej, możesz zastąpić ją domyślną tarczą zegarka.

Dzięki temu tarcza zegarka będzie zawsze dostępna w systemowym selektorze tarcz, może zawierać Twoje logo i może mieć nawet przycisk do uruchamiania aplikacji z Marketplace na telefonie.

Sprawdzanie, czy tarcza zegarka jest aktywna

Sprawdzenie, czy na platformie jest ustawiona aktywna tarcza zegarka, jest ważne, aby zapewnić użytkownikowi płynne działanie: jeśli na platformie jest już ustawiona aktywna tarcza zegarka, użytkownik, który chce wybrać inną tarczę, musi tylko zastąpić bieżącą tarczę za pomocą aplikacji platformy, aby zmiana została wprowadzona. Jeśli jednak w usłudze nie jest ustawiona aktywna tarcza zegarka, aplikacja na telefon musi zawierać więcej wskazówek dla użytkownika. Więcej informacji o tym, jak zadbać o wygodę użytkowników, znajdziesz w sekcji dotyczącej aplikacji na telefon.

Aby sprawdzić, czy na platformie jest ustawiona aktywna tarcza zegarka, użyj tej logiki:

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

Ostrzeżenie: po wybraniu numeru updateWatchFace() nie dzwoń od razu pod numer isWatchFaceActive(), ponieważ może to spowodować nieoczekiwane rezultaty. Zmiana tarczy zegarka może trochę potrwać.

Zamiast tego najpierw sprawdź, czy aplikacja wywołująca ma odniesienie do aktywnej tarczy zegarka, jak pokazano w poprzednim fragmencie kodu, a następnie wywołaj funkcję updateWatchFace(). Jeśli updateWatchFace() zakończy się pomyślnie, możesz założyć, że aplikacja nadal ma kontrolę nad aktywną tarczą zegarka.

Podaj domyślną tarczę zegarka

Funkcja Watch Face Push umożliwia zainstalowanie domyślnej tarczy zegarka po zainstalowaniu aplikacji z platformy handlowej. Samo to nie powoduje ustawienia domyślnej tarczy zegarka jako aktywnej (patrz ustawianie aktywnej tarczy zegarka), ale sprawia, że tarcza zegarka jest dostępna w systemowym selektorze tarcz zegarka.

Aby korzystać z tej funkcji:

1. W kompilacji aplikacji 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" />
   

Uwaga: typowy wzorzec kompilacji obejmuje tworzenie default_watchface.apk w ramach ogólnej kompilacji aplikacji jako krok wstępny. Możesz użyć tej metody, aby wypełnić wartość manifestu tokena weryfikacyjnego, sprawiając, że domyślny proces kompilacji tarczy zegarka wygeneruje dodatkowy plik XML zasobów Androida i uwzględni ścieżkę do tych zasobów jako dodatkową ścieżkę do zasobów w głównej aplikacji. To podejście jest prostsze niż próba manipulowania samym plikiem manifestu podczas procesu kompilacji.

Ustawianie aktywnej tarczy zegarka

Funkcja Watch Face Push umożliwia aplikacji na platformie handlowej ustawienie aktywnej tarczy zegarka.

Oznacza to, że aplikacja może ustawić aktywną tarczę zegarka na tarczę należącą do platformy, jeśli bieżąca aktywna tarcza zegarka nie należy do platformy. Pamiętaj, że jeśli na platformie jest już aktywna tarcza zegarka, zmiana na inną tarczę odbywa się przez wywołanie funkcji updateWatchFace, która zastępuje zawartość gniazda tarczy zegarka inną tarczą.

Ustawianie aktywnej tarczy zegarka to proces dwuetapowy:

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 należy dodać 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>

Jest to uprawnienie przyznawane w czasie działania, więc aplikacja musi poprosić o nie użytkownika podczas działania (możesz skorzystać z biblioteki Accompanist).

Uwaga: to uprawnienie może być odrzucone tylko raz. Jeśli użytkownik odrzuci prośbę, nie można jej ponownie wysłać. W takim przypadku aplikacja powinna przekierować użytkownika do ustawień, aby mógł ręcznie dostosować uprawnienia.

Ustaw tarczę zegarka jako aktywną

Po przyznaniu uprawnień wywołaj funkcję setWatchFaceAsActive z identyfikatorem gniazda tarczy zegara, która ma być aktywna:

watchFacePushManager.setWatchFaceAsActive(slotId)

Uwaga: aktywną tarczę zegarka można ustawić w ten sposób tylko raz. Jeśli użytkownik przejdzie na tarczę zegarka innego dewelopera, wywołanie tego interfejsu API w celu przywrócenia aktywnej tarczy zegarka spowoduje zgłoszenie wyjątku.

Po użyciu tego sposobu aplikacja na telefon powinna wyświetlać instrukcje ręcznego ustawiania aktywnej tarczy zegarka.

Odczytywanie dodatkowych metadanych 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 tej samej tarczy zegarka. Możesz na przykład zdefiniować tarczę zegara w ten sposób:

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

Ta tarcza zegarka może być jednak dostępna w 4 różnych plikach APK, które są niemal identyczne, ale mają różne kolory domyślne: czerwony, żółty, zielony i niebieski, ustawione w ColorConfiguration w pliku XML formatu tarczy zegarka.

Ta niewielka różnica jest odzwierciedlana w każdym z 4 plików APK:

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

Użycie właściwości niestandardowej umożliwia aplikacji określenie, która z tych wersji jest zainstalowana:

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

Uwaga: w poprzednim przykładzie przestrzeń nazw musiała zostać podana dla właściwości, ponieważ w niej zadeklarowano none. Jeśli właściwość zawiera kropkę (.), nie jest to konieczne, więc właściwość o nazwie abc.def można pobrać za pomocą getMetaDataValues("abc.def").

co należy wziąć pod uwagę

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

Moc

Kluczowym aspektem każdej aplikacji działającej na Wear OS jest zużycie energii. W przypadku komponentu Wear OS aplikacji na platformę handlową:

1. Aplikacja powinna działać jak najrzadziej i jak najkrócej (chyba że użytkownik bezpośrednio z niej korzysta). Obejmuje to:
   • Minimalizowanie wybudzania aplikacji z aplikacji na telefon
   • Minimalizowanie uruchamiania zadań WorkManager
2. Zaplanuj raportowanie analityczne na czas ładowania zegarka:
   1. Jeśli chcesz raportować statystyki użytkowania z aplikacji na Wear OS lub inne dane, użyj WorkManagera z ograniczeniem requiresCharging.
3. Zaplanuj aktualizacje na czas ładowania zegarka i korzystaj z Wi-Fi:
   1. Możesz sprawdzić wersje zainstalowanych tarcz zegarka i automatycznie je zaktualizować. Ponownie użyj ograniczenia requiresCharging i typu sieci UNMETERED dla requiresNetworkType.
   2. Podczas ładowania urządzenie prawdopodobnie ma dostęp do Wi-Fi. Poproś o Wi-Fi, aby szybko pobrać zaktualizowane pliki APK, i zwolnij sieć po zakończeniu.
   3. Te same wskazówki dotyczą sytuacji, w której platforma handlowa może oferować tarczę zegarka dnia. Pobierz ją wstępnie podczas ładowania zegarka.
4. Nie planuj zadań sprawdzających aktywną tarczę zegarka:
   1. Okresowe sprawdzanie, czy na platformie nadal jest aktywna tarcza zegarka, i która to jest tarcza, zużywa baterię. Unikaj takiego podejścia.
5. Nie używaj powiadomień na zegarku:
   1. Jeśli Twoja aplikacja korzysta z powiadomień, skup się na telefonie, w którym działanie użytkownika otwiera aplikację na telefonie, aby kontynuować proces. Sprawdź, czy nie są one przekazywane do aplikacji na zegarku za pomocą setLocalOnly.

Buforowanie

W przykładzie z kanoniczną platformą handlową tarcze zegarka są przesyłane z telefonu na zegarek. Zwykle jest to połączenie Bluetooth, które może być dość wolne.

Aby zapewnić lepsze wrażenia użytkownikom i oszczędzać energię potrzebną do ponownej transmisji, rozważ wdrożenie małej pamięci podręcznej na urządzeniu z Wear OS, w której będzie można przechowywać kilka plików APK.

Jeśli użytkownik wypróbuje inną tarczę zegarka, a potem zdecyduje się wrócić do wcześniej wybranej, ta czynność będzie niemal natychmiastowa.

Podobnie można to wykorzystać do wstępnego buforowania tarczy zegarka dnia lub podobnych schematów, w których tarcze zegarka 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 zegara jest instalowana w systemie po zainstalowaniu aplikacji z platformy, nie jest ona aktualizowana, jeśli nowsza wersja jest dołączona do aktualizacji aplikacji z platformy.

Aby sobie z tym poradzić, aplikacja platformy handlowej powinna nasłuchiwać działania transmisji MY_PACKAGE_REPLACED i sprawdzać, czy trzeba zaktualizować którąś z dołączonych tarcz zegara z zasobów pakietu.

Reprezentatywna domyślna tarcza zegarka

Domyślna tarcza zegarka to świetny sposób na ułatwienie użytkownikom odkrywania i korzystania z Twojego sklepu: tarcza zegarka jest instalowana wraz ze sklepem, więc użytkownicy mogą ją znaleźć w galerii tarcz zegarka.

Oto kilka kwestii, o których warto pamiętać podczas korzystania z domyślnych tarcz zegarka:

• Nie używaj removeWatchFace, jeśli użytkownik zdecyduje się odinstalować tarczę zegarka z aplikacji na platformie handlowej. W takim przypadku przywróć domyślną tarczę zegarka za pomocą updateWatchFace. Ułatwi to użytkownikom znalezienie tarczy zegarka i ustawienie jej z galerii.
• Spraw, aby domyślna tarcza zegarka była prosta i natychmiast rozpoznawalna dzięki logo i motywowi. Ułatwi to użytkownikom znalezienie jej w galerii tarcz zegarka.

• Dodaj przycisk do domyślnej tarczy zegara, aby otworzyć aplikację telefonu. Możesz to zrobić w 2 etapach:

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

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

  2. W LaunchOnPhoneActivity uruchom aplikację Telefon, klikając RemoteActivityHelper.