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:
- File (Dosya) > New (Yeni) > New project (Yeni proje) seçeneğini tıklayın.
- Proje Şablonu penceresinde Wear OS sekmesini tıklayın, Etkinlik Yok'u seçin ve İleri'yi tıklayın.
- Projenizi Yapılandırın penceresinde, projenize bir ad verin, standart proje bilgilerini doldurun ve Sonlandır'ı tıklayın.
- 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.
-
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çinComplicationProviderService
kapsamını genişleten yeni bir sınıf oluşturun. Daha fazla bilgi için aşağıdaki konulara bakın:- Güncelleme istekleri için bir yöntem uygulama
- Aşağıdaki codelab'de yer alan
ComplicationTapBroadcastReceiver
veCustomComplicationProviderService
sınıfları: Verileri Wear OS'te kadran özelliklerine gösterme -
Test paketi örneğindeki
ComplicationToggleReceiver
,LongTextProviderService
ve diğer sınıflar
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:
- Dinamik değer bazen mevcut olmayabilir: Bu durum, örneğin, cihaz bileğinizde değilken kullanılabilir. Böyle durumlarda platform, bunun yerine
NoDataComplicationData
'in yer tutucu alanında dinamik değer geçersiz kılma yedek alanının değerini kullanır. - Dinamik değer hiçbir zaman kullanılamıyor: Bu durum, Wear OS 4'ün eski bir sürümünü çalıştıran bir cihazda gerçekleşir. Bu durumda, platform
getFallbackValue()
gibi bir tamamlayıcı yedek alanı kullanır.
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.