Подвергайте данные осложнениям

Приложения-поставщики данных предоставляют информацию для усложнения циферблата, предоставляя поля, содержащие текст, строки, изображения и числа.

Служба поставщика данных расширяет ComplicationProviderService , чтобы доставлять полезную информацию непосредственно на циферблат.

Создание проекта поставщика данных

Чтобы создать проект в Android Studio для вашего приложения поставщика данных, выполните следующие шаги:

  1. Нажмите Файл > Создать > Новый проект .
  2. В окне «Шаблон проекта» перейдите на вкладку Wear OS, выберите «Нет активности» и нажмите «Далее» .
  3. В окне «Настройка проекта» укажите имя своего проекта, заполните стандартную информацию о проекте и нажмите « Готово» .
  4. Android Studio создает проект с модулем приложения для вашего поставщика данных. Дополнительные сведения о проектах в Android Studio см. в разделе Создание проекта .
  5. Начните свое приложение поставщика данных с создания нового класса, расширяющего BroadcastReceiver . Цель этого класса — прослушивать запросы на усложнение обновлений от системы Wear OS. Кроме того, создайте новый класс, который расширяет ComplicationProviderService для предоставления данных по запросу соответствующих осложнений. Для получения дополнительной информации см. следующее:

    Примечание. Добавление действия для вашего поставщика данных не является обязательным. Например, вам может потребоваться действие, которое запускается только тогда, когда пользователь нажимает на сложность.

Реализация метода для запросов на обновление

Когда требуются сложные данные, система Wear OS отправляет запросы на обновление вашему поставщику данных. Запросы принимаются вашим BroadcastReceiver . Чтобы ответить на запросы обновления, ваш поставщик данных должен реализовать метод onComplicationUpdate() класса ComplicationProviderService .

Система Wear OS вызывает onComplicationUpdate() когда ей нужны данные от вашего провайдера — например, когда осложнение, связанное с вашим провайдером, становится активным или когда проходит фиксированный промежуток времени. Он передает объект ComplicationManager в качестве параметра в onComplicationUpdate , который используется для отправки данных обратно в систему.

Примечание. Когда приложение вашего поставщика данных предоставляет данные, циферблат получает отправленные вами необработанные значения, чтобы он мог получить информацию.

В следующем фрагменте кода показан пример реализации метода onComplicationUpdate :

Котлин 

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)
    }
}

Ява 

@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);
   }
}

Манифестные декларации и разрешения

Приложения-поставщики данных должны включать в манифест приложения определенные объявления, чтобы система Android воспринимала их как поставщика данных. В этом разделе описаны необходимые настройки для приложений поставщиков данных.

В манифесте вашего приложения объявите службу и добавьте фильтр намерения действия запроса на обновление. Манифест также должен защищать службу, добавляя разрешение BIND_COMPLICATION_PROVIDER чтобы гарантировать, что только система Wear OS может привязываться к службам поставщика.

Кроме того, включите атрибут android:icon в элемент service , который предоставляет одноцветный белый значок. Мы рекомендуем векторные изображения для иконок. Значок представляет поставщика и отображается в списке поставщиков.

Вот пример:

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

Укажите элементы метаданных

В файл манифеста включите метаданные, чтобы указать поддерживаемые типы, период обновления и действие настройки, как показано в следующем примере:

<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" />

Когда ваш поставщик данных об осложнениях активен, UPDATE_PERIOD_SECONDS указывает, как часто вы хотите, чтобы система проверяла наличие обновлений данных. Если информация, отображаемая в расширении, не требует регулярного обновления, например, когда вы используете push-обновления , установите для этого значения значение 0 .

Если вы не установили для UPDATE_PERIOD_SECONDS значение 0 , вы должны использовать значение не менее 300 (5 минут), что является минимальным периодом обновления, который обеспечивает система, чтобы продлить срок службы батареи устройства. Кроме того, имейте в виду, что запросы на обновление поступают реже, когда устройство находится в обычном режиме или не на нем.

Дополнительные сведения об отправке обновлений см. в ключах, перечисленных для класса ComplicationProviderService в справочнике по API Wear OS .

Добавить действие по настройке

При необходимости поставщик может включить действие по настройке, которое отображается пользователю, когда пользователь выбирает поставщика данных. Чтобы включить действие по настройке, включите элемент метаданных в декларацию службы поставщика в манифесте со следующим ключом:

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

Значением может быть любое действие.

Затем создайте действие настройки с фильтром намерений для этого действия. Действие настройки должно находиться в том же пакете, что и поставщик. Действие настройки должно вернуть RESULT_OK или RESULT_CANCELED чтобы сообщить системе, следует ли установить поставщика.

Безопасные циферблаты, указанные поставщиком

Провайдеры могут указать определенные циферблаты как «безопасные» для получения своих данных. Это используется только тогда, когда циферблат пытается использовать поставщика по умолчанию, и поставщик доверяет приложению циферблата.

Чтобы объявить циферблаты безопасными, поставщик добавляет метаданные с ключом android.support.wearable.complications.SAFE_WATCH_FACES . Значение метаданных представляет собой разделенный запятыми список имен компонентов WatchFaceService , заданных так, как будто вызывается ComponentName.flattenToString() , или имен пакетов приложений, и в этом случае каждый циферблат в указанном приложении считается безопасным. Пробелы в списке значений игнорируются. Например:

<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"/>

Обеспечьте безопасные для выгорания изображения

На экранах, подверженных выгоранию, следует избегать сплошных цветных блоков в окружающем режиме. Если ваши значки или изображения содержат сплошные цветные блоки, предоставьте также версию, безопасную для записи.

При предоставлении значка с помощью ComplicationData.Builder#setIcon включите версию, безопасную для записи, с помощью ComplicationData.Builder#setBurnInProtectionIcon .

Когда вы предоставляете изображение с помощью ComplicationData.Builder#setSmallImage , включите безопасную для записи версию с помощью ComplicationData.Builder#setBurnInProtectionSmallImage .

Используйте push-обновления

В качестве альтернативы указанию постоянного ненулевого интервала обновления для осложнения в манифесте вашего приложения вы можете использовать экземпляр ComplicationDataSourceUpdateRequester для динамического запроса обновлений. Чтобы запросить обновление видимого пользователю содержимого сложности, вызовите requestUpdate() .

Предупреждение. Чтобы продлить срок службы батареи устройства, не вызывайте requestUpdate() из экземпляра ComplicationDataSourceUpdateRequester чаще, чем в среднем каждые 5 минут.

Предоставьте динамические значения

Начиная с Wear OS 4, некоторые сложности могут отображать значения, которые обновляются чаще на основе значений, доступных непосредственно на платформе. Чтобы обеспечить эту возможность в ваших сложностях, используйте поля ComplicationData , которые принимают динамические значения . Платформа часто оценивает и обновляет эти значения, не требуя запуска поставщика осложнений.

Примеры полей включают поле динамического значения GoalProgressComplicationData и DynamicComplicationText , которое можно использовать в любом поле ComplicationText . Эти динамические значения основаны на библиотеке androidx.wear.protolayout.expression .

В определенных ситуациях платформа не может оценивать динамические значения:

Укажите значения, зависящие от времени

Некоторые сложности требуют отображения значения, относящегося к текущему времени. Примеры включают текущую дату, время до следующей встречи или время в другом часовом поясе.

Не обновляйте усложнение каждую секунду или минуту, чтобы поддерживать актуальность этих значений. Вместо этого укажите значения относительно текущей даты или времени, используя текст, зависящий от времени. Вы можете использовать построители в классе ComplicationText для создания этих зависящих от времени значений.

Частота обновления осложнений

Возможно, вам захочется быстро обновлять сведения о осложнениях. Однако это может повлиять на срок службы батареи устройства. Вы можете использовать привилегированный API запроса на усложнение , который позволяет чаще обновлять определенные осложнения. Однако использование этого API должно быть разрешено производителем часов . Каждый производитель часов решает, какие усложнения могут обновляться быстрее, чем обычно допускается.