Özelliklere verileri gösterme

Veri sağlayıcı uygulamaları; metin, dize, resim ve sayı içeren alanlar sağlayarak kadran özelliklerine bilgileri açığa çıkarır.

Bir veri sağlayıcı hizmeti, faydalı bilgileri doğrudan saat yüzüne sunmak için ComplicationProviderService hizmetinin kapsamını genişletir.

Veri sağlayıcı projesi oluşturma

Android Studio'da veri sağlayıcı uygulamanız için bir proje oluşturmak üzere aşağıdaki adımları tamamlayın:

  1. File (Dosya) > New (Yeni) > New project (Yeni proje) seçeneğini tıklayın.
  2. Proje Şablonu penceresinde Wear OS sekmesini tıklayın, Etkinlik Yok'u seçin ve İleri'yi tıklayın.
  3. Projenizi Yapılandırın penceresinde, projenize bir ad verin, standart proje bilgilerini doldurun ve Sonlandır'ı tıklayın.
  4. Android Studio, veri sağlayıcınız için bir uygulama modülü içeren bir proje oluşturur. Android Studio'daki projeler hakkında daha fazla bilgi için Proje oluşturma bölümüne bakın.
  5. BroadcastReceiver aralığını kapsayan yeni bir sınıf oluşturarak veri sağlayıcı uygulamanıza başlayın. Bu sınıfın amacı, Wear OS sisteminden özellik güncelleme isteklerini dinlemektir. Ayrıca, uygun özelliklerin gerektirdiği şekilde veri sağlamak için ComplicationProviderService kapsamını genişleten yeni bir sınıf oluşturun. Daha fazla bilgi için aşağıdaki konulara bakın:

    Not: Veri sağlayıcınız için etkinlik eklemek isteğe bağlıdır. Örneğin, yalnızca kullanıcı bir özelliğe dokunduğunda başlatılan bir etkinlik isteyebilirsiniz.

Güncelleme istekleri için bir yöntem uygulama

Özellik verileri gerektiğinde Wear OS sistemi, veri sağlayıcınıza güncelleme istekleri gönderir. İstekler BroadcastReceiver tarafından alınır. Güncelleme isteklerine yanıt vermek için veri sağlayıcınızın, ComplicationProviderService sınıfının onComplicationUpdate() yöntemini uygulaması gerekir.

Wear OS sistemi, sağlayıcınızdan veri alınması gerektiğinde (örneğin, sağlayıcınızı kullanan bir özellik etkin hale geldiğinde veya belirli bir süre geçtiğinde) onComplicationUpdate() işlevini çağırır. Sisteme veri göndermek için kullanılan onComplicationUpdate öğesine parametre olarak bir ComplicationManager nesnesi iletir.

Not: Veri sağlayıcı uygulamanız veri sağladığında, kadrana gönderdiğiniz ham değerleri alır. Böylece bilgileri alabilir.

Aşağıdaki kod snippet'i, onComplicationUpdate yönteminin örnek bir uygulamasını göstermektedir:

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

Manifest beyanları ve izinler

Veri sağlayıcı uygulamalarının Android sistemi tarafından veri sağlayıcı olarak değerlendirilmesi için uygulama manifest dosyalarında belirli beyanlar yer almalıdır. Bu bölümde veri sağlayıcı uygulamaları için gerekli ayarlar açıklanmaktadır.

Uygulamanızın manifest dosyasında hizmeti tanımlayın ve güncelleme isteği işlem intent filtresi ekleyin. Ayrıca manifest, sağlayıcı hizmetlerine yalnızca Wear OS sisteminin bağlanabildiğinden emin olmak için BIND_COMPLICATION_PROVIDER iznini ekleyerek hizmeti korumalıdır.

Ayrıca, tek renkli beyaz simge sağlayan service öğesine bir android:icon özelliği ekleyin. Simgeler için vektör çekilebilir yollarını öneririz. Simge, sağlayıcıyı temsil eder ve sağlayıcı seçicide gösterilir.

Aşağıda bununla ilgili bir örnek verilmiştir:

<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 veri öğelerini belirtme

Aşağıdaki örnekte gösterildiği gibi, desteklenen türleri, güncelleme dönemini ve yapılandırma işlemini belirtmek için manifest dosyanıza meta veri ekleyin:

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

Özellik verisi sağlayıcınız etkinken UPDATE_PERIOD_SECONDS, sistemin verilerdeki güncellemeleri ne sıklıkta kontrol etmesini istediğinizi belirtir. Özellikte gösterilen bilgilerin düzenli bir şekilde güncellenmesi gerekmiyorsa (örneğin, Push güncellemeleri kullanıyorsanız) bu değeri 0 olarak ayarlayın.

UPDATE_PERIOD_SECONDS öğesini 0 olarak ayarlamazsanız cihazın pil ömrünü korumak için en az 300 (5 dakika) değeri kullanmanız gerekir. Bu, sistemin uyguladığı minimum güncelleme süresidir. Bu süre, cihazın pil ömrünü korur. Ayrıca, cihaz ambiyans modundayken veya giyinmediğinde güncelleme isteklerinin daha az geldiğini unutmayın.

Güncelleme gönderme hakkında daha fazla bilgi edinmek için Wear OS API Referansı'nda ComplicationProviderService sınıfı için listelenen anahtarlara göz atın.

Yapılandırma etkinliği ekleme

Gerekirse sağlayıcı, kullanıcı bir veri sağlayıcı seçtiğinde kullanıcıya gösterilecek bir yapılandırma etkinliği ekleyebilir. Yapılandırma etkinliğini dahil etmek için manifest dosyasındaki sağlayıcı hizmet bildirimine aşağıdaki anahtarla bir meta veri öğesi ekleyin:

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

Değer, herhangi bir işlem olabilir.

Ardından, bu işlem için bir amaç filtresiyle yapılandırma etkinliği oluşturun. Yapılandırma etkinliği, sağlayıcıyla aynı pakette bulunmalıdır. Yapılandırma etkinliği, sisteme sağlayıcının ayarlanması gerekip gerekmediğini bildirmek için RESULT_OK veya RESULT_CANCELED döndürmelidir.

Sağlayıcı tarafından belirtilen güvenli saat yüzleri

Sağlayıcılar, belirli kadranların verilerini almanın "güvenli" olduğunu belirtebilir. Bu yalnızca bir kadran, sağlayıcıyı varsayılan olarak kullanmaya çalıştığında ve sağlayıcı kadran uygulamasına güvendiğinde kullanılır.

Sağlayıcı, kadranların güvenli olduğunu belirtmek için meta verileri android.support.wearable.complications.SAFE_WATCH_FACES anahtarıyla ekler. Meta veri değeri, ComponentName.flattenToString() çağrılımış gibi verilen WatchFaceService bileşen adlarının veya uygulama paketi adlarının (bu durumda belirtilen bir uygulamadaki her kadran güvenli kabul edilir) virgülle ayrılmış listesidir. Değer listesindeki boşluk yok sayılır. Örnek:

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

Yanma açısından güvenli resimler sağlayın

Yanmaya karşı hassas olan ekranlarda, ambiyans modunda düz renk blokları kullanılmamalıdır. Simgeleriniz veya resimleriniz düz renk blokları içeriyorsa pikselin yanmasına güvenli bir sürümünü de sağlayın.

ComplicationData.Builder#setIcon kullanarak simge sağlarken ComplicationData.Builder#setBurnInProtectionIcon kullanarak yerleşik güvenli bir sürüm ekleyin.

ComplicationData.Builder#setSmallImage kullanarak görüntü sağladığınızda, ComplicationData.Builder#setBurnInProtectionSmallImage kullanarak pikselin yanabileceği güvenli bir sürüm ekleyin.

Push güncellemelerini kullanma

Uygulamanızın manifest dosyasındaki bir özellik için sabit, sıfır olmayan bir güncelleme aralığı belirtmeye alternatif olarak, güncellemeleri dinamik olarak istemek için bir ComplicationDataSourceUpdateRequester örneği kullanabilirsiniz. Özelliğin kullanıcılar tarafından görülebilen içeriğinde güncelleme isteğinde bulunmak için requestUpdate() numaralı telefonu arayın.

Dikkat: Cihazın pil ömrünü korumak için, ComplicationDataSourceUpdateRequester örneğinizden requestUpdate() çağrısını ortalama 5 dakikada bir daha sık yapmayın.

Dinamik değerler sağlama

Wear OS 4'ten itibaren, bazı özellikler doğrudan platformda kullanılabilen değerlere göre daha sık yenilenen değerler gösterebilir. Özelliklerinizde bu özelliği sağlamak için dinamik değerleri kabul eden ComplicationData alanlarını kullanın. Platform, komplikasyon sağlayıcının çalışmasına gerek kalmadan bu değerleri sık sık değerlendirip günceller.

Örnek alanlar arasında GoalProgressComplicationData dinamik değer alanı ve herhangi bir ComplicationText alanında kullanılabilen DynamicComplicationText yer alır. Bu dinamik değerler, androidx.wear.protolayout.expression kitaplığını temel alır.

Belirli durumlarda platform dinamik değerleri değerlendiremez:

Zamana bağlı değerler sağlama

Bazı özelliklerin mevcut saate uygun bir değer göstermesi gerekir. Geçerli tarih, bir sonraki toplantıya kadar olan saat veya başka bir saat dilimindeki saat buna örnek olarak verilebilir.

Değerleri güncel tutmak için bir özelliği her saniye veya dakikada bir güncellemeyin. Bunun yerine, zamana bağlı metin kullanarak değerleri geçerli tarihe veya saate göre belirtin. Bu zamana bağlı değerleri oluşturmak için ComplicationText sınıfındaki oluşturucuları kullanabilirsiniz.

Özellik güncelleme oranı

Özellikleri hızlı bir şekilde güncellemek isteyebilirsiniz. Ancak bu, cihazın pil ömrünü etkileyebilir. Belirli özelliklerin daha sık güncellenmesini sağlayan ayrıcalıklı bir Komplikasyon isteği API'si kullanmayı seçebilirsiniz. Bununla birlikte, saat üreticisi tarafından bu API'nin kullanımına izin verilmelidir. Her saat üreticisi, hangi özelliklerin izin verilenden daha hızlı bir şekilde güncellenebileceğine karar verir.