Narażenie danych na widżety

Aplikacje dostawcy danych ujawniają informacje na tarczy zegarka powikłań, dostarczając pola zawierające tekst, ciągi tekstowe, obrazy i liczby.

Rozszerzenie usługi dostawcy danych ComplicationProviderService, aby wyświetlać przydatne bezpośrednio na tarczę zegarka.

Utwórz projekt dostawcy danych

Aby utworzyć projektu dostawcy danych w Android Studio, wykonaj te czynności:

  1. Kliknij Plik > Nowe > Nowy projekt.
  2. W oknie Szablon projektu kliknij kartę Wear OS, a potem wybierz Brak aktywności i kliknij Dalej.
  3. W oknie Skonfiguruj projekt wpisz nazwę projektu i wypełnij (standardowe informacje o projekcie) i kliknij Finish (Zakończ).
  4. Android Studio utworzy projekt z modułem aplikacji dostawcy danych. Więcej informacje o projektach w Android Studio, zobacz Utwórz projekt.
  5. Rozpocznij aplikację dostawcy danych od utworzenia nowej klasy, która obejmuje BroadcastReceiver Celem tych zajęć jest słuchanie aktualizacji widżetów z systemu Wear OS. Dodatkowo utwórz nowe zajęcia, które obejmują ComplicationProviderService, aby dostarczyć dane zgodnie z wymaganiami odpowiednich widżetów. Więcej informacji:

    Uwaga: dodanie aktywności dla dostawcy danych jest opcjonalnie. Możesz na przykład określić aktywność, która będzie uruchamiana tylko wtedy, gdy użytkownik kliknie widżet.

Wdrażanie metody obsługi żądań aktualizacji

Gdy potrzebne są dane widżetu, system Wear OS wysyła do Twoich danych żądania aktualizacji dostawcy usług. Żądania są wysyłane przez BroadcastReceiver Aby odpowiedzieć na prośby o aktualizację, dostawca danych musi zaimplementować Metoda onComplicationUpdate() algorytmu ComplicationProviderService zajęcia.

System Wear OS wywołuje metodę onComplicationUpdate(), gdy potrzebuje danych z Twojego dostawcy, np. gdy widżet korzystający z niego staje się aktywny lub po upływie ustalonego czasu. Przechodzi ComplicationManager jako parametru funkcji onComplicationUpdate – służy do przesyłania danych z powrotem do systemu.

Uwaga: jeśli aplikacja dostawcy danych przekazuje dane, tarcza zegarka otrzymuje nieprzetworzone wartości, które wysyłasz, aby móc narysować informacje.

Fragment kodu poniżej zawiera przykładową implementację funkcji Metoda onComplicationUpdate:

Kotlin

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

Java

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

Deklaracje i uprawnienia w pliku manifestu

Aplikacje dostawcy danych muszą zawierać w pliku manifestu określone deklaracje, aby były traktowane jako dostawcą danych w systemie Android. W tej sekcji opisano wymagane ustawienia aplikacji dostawców danych.

W pliku manifestu aplikacji zadeklaruj usługę i dodaj filtr intencji działania żądania aktualizacji. Plik manifestu musi też chronić usługę przez dodanie elementu BIND_COMPLICATION_PROVIDER aby mieć pewność, że tylko system Wear OS może tworzyć powiązania z usługami dostawcy.

Umieść też atrybut android:icon w Element service, który udostępnia jednokolorową, białą ikonę. Zalecamy użycie elementów rysowalnych wektorowo. Ikona symbolizująca dostawcę i widoczna u dostawcy selektor.

Oto przykład: 

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action
         android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST"/>
    </intent-filter>
</service>

Określanie elementów metadanych

W pliku manifestu uwzględnij metadane określające obsługiwane typy plików, okresu aktualizacji i działania konfiguracyjnego, jak pokazano poniżej. przykład: 

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" />

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="300" />

Gdy dostawca danych do widżetu jest aktywny, UPDATE_PERIOD_SECONDS określa, jak często ma być sprawdź dostępność aktualizacji danych. Jeśli informacje w sekcji widżet nie musi być aktualizowany regularnie, na przykład używasz aktualizacji push, ustaw tę wartość na 0

Jeśli nie ustawisz wartości 0 na UPDATE_PERIOD_SECONDS, musisz użyć wartości co najmniej 300 (5 minut), która jest minimalny okres aktualizacji wymuszany przez system, żywotności baterii urządzenia. Ponadto należy pamiętać, że żądania aktualizacji pojawia się rzadziej, gdy urządzenie jest w trybie nieaktywnym lub gdy nie jest założone.

Więcej informacji o wysyłaniu aktualizacji znajdziesz na liście kluczy ComplicationProviderService zajęcia w Wear OS API Materiały referencyjne.

Dodaj aktywność związaną z konfiguracją

W razie potrzeby dostawca może dołączyć aktywność związaną z konfiguracją, która jest wyświetlane, gdy użytkownik wybierze dostawcę danych. Aby użyć parametru aktywności konfiguracji, umieść element metadanych w usłudze dostawcy w pliku manifestu z tym kluczem: 

<meta-data
    android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
    android:value="PROVIDER_CONFIG_ACTION"/>

Wartością może być dowolne działanie.

Następnie utwórz aktywność związaną z konfiguracją z filtrem intencji, działania. Aktywność konfiguracji musi znajdować się w tym samym pakiecie co dostawcy usług. Aktywność konfiguracji musi zwracać wartość RESULT_OK lub RESULT_CANCELED, aby poinformować system, czy dostawca powinna być ustawiona.

Tarcze bezpiecznych zegarków określone przez dostawcę

Dostawcy mogą oznaczać niektóre tarcze zegarka jako „bezpieczne” aby otrzymać i skalowalnych danych. Ta opcja jest używana tylko wtedy, gdy tarcza próbuje aby domyślnie używać tego dostawcy a dostawca ma zaufanie do aplikacji tarczy zegarka.

Aby zadeklarować tarcze zegarka jako bezpieczne, dostawca dodaje metadane z kluczem android.support.wearable.complications.SAFE_WATCH_FACES jest rozdzielaną przecinkami listą: WatchFaceService nazwy komponentów, tak jakby Dzwoni ComponentName.flattenToString() lub nazw pakietów aplikacji. W takim przypadku każda tarcza zegarka została uznana za bezpieczną. Odstępy na liście wartości są ignorowane. Na przykład: 

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

Zapewniaj możliwość wypalania obrazów

Na ekranach odpornych na wypalenie należy unikać jednolitych bloków koloru w trybie nieaktywnym. Jeśli ikony lub obrazy zawierają jednolite bloki koloru, i zapewnić bezpieczną wersję.

Jeśli podasz ikonę za pomocą ComplicationData.Builder#setIcon, uwzględnij wersję bezpieczną do wypalenia; za pomocą . ComplicationData.Builder#setBurnInProtectionIcon

Gdy udostępnisz obraz za pomocą atrybutu ComplicationData.Builder#setSmallImage, uwzględnij wersję bezpieczną do wypalenia; za pomocą . ComplicationData.Builder#setBurnInProtectionSmallImage

Użycie aktualizacji push

Jako alternatywę do określania stałego, niezerowego interwału aktualizacji dla w pliku manifestu aplikacji, możesz użyć instancji ComplicationDataSourceUpdateRequester, aby wysyłać żądania aktualizacji dynamicznie. Aby poprosić o aktualizację treści widocznych dla użytkowników, wywołaj requestUpdate()

Uwaga: aby wydłużyć czas pracy urządzenia na baterii, nie wywołuj funkcji requestUpdate() z instancji ComplicationDataSourceUpdateRequester częściej niż co 5 minut w: średnią.

Podawanie wartości dynamicznych

Począwszy od Wear OS 4 niektóre widżety mogą wyświetlać wartości, które są odświeżane częściej na podstawie wartości dostępnych bezpośrednio na platformie. Aby udostępnić tę możliwość w do usunięcia komplikacji, Akceptowane pola: ComplicationData wartości dynamicznych. Platforma ocenia często aktualizuje te wartości bez konieczności uruchamiania dostawcy widżetu.

Przykładowe pola obejmują GoalProgressComplicationData w polu wartości dynamicznej oraz . DynamicComplicationText, której można używać w dowolnych ComplicationText. Te wartości dynamiczne opierają się na androidx.wear.protolayout.expression.

W niektórych sytuacjach platforma nie może ocenić wartości dynamicznych:

Podaj wartości zależne od czasu

Niektóre widżety muszą wyświetlać wartość związaną z bieżącymi obecnie się znajdujesz. Może to być na przykład bieżąca data, czas do następnego spotkania, albo godzina w innej strefie czasowej.

Nie aktualizuj widżetu co co minutę lub minutę, aby zapewnić aktualność tych wartości. Zamiast tego wpisz wartości względem bieżącej daty lub godziny przy użyciu tekstu zależnego od czasu. Kreatorów można używać na stronie ComplicationText, aby utworzyć te wartości zależne od czasu.

Częstotliwość aktualizacji widżetów

Możesz szybko aktualizować widżety. Może to jednak mieć wpływ na baterię przez cały okres użytkowania urządzenia. Możesz wybrać użycie Interfejs API żądania widżetu, który umożliwia częstsze aktualizowanie określonych widżetów. Jednak korzystanie z tego interfejsu API musi dozwolonych przez producenta zegarka. Każdy producent zegarka decyduje, które widżety można zaktualizować szybsze niż zwykle.