Wear OS uygulamanızı kadran itme için yapılandırma

Kadranı gönderme özelliği, uygulamanızın Wear OS cihazlardaki kadranları yönetmesine olanak tanır. Kadran ekleme, güncelleme ve kaldırmanın yanı sıra etkin kadranı ayarlama da bu kapsamdadır. Wear OS uygulamanızı Watch Face Push API'yi kullanacak şekilde yapılandırın.

Kurulum

androidx.wear.watchfacepush:watchfacepush bağımlılığını build.gradle.kts dosyanıza ekleyin.

AndroidManifest.xml öğenize aşağıdakileri ekleyin:

<!-- Required to use the Watch Face Push API.  -->
<uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />
AndroidManifest.xml

Yönetici örneğine referans alma

WatchFacePushManager örneğini edinme:

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)
WatchFacePush.kt

WatchFacePushManager, Watch Face Push ile etkileşim kurma yöntemlerinin tümüne erişim sağlar.

Slotlarla çalışma

Watch Face Push ile çalışırken önemli bir kavram yuvalardır. Yuvalar, uygulamanıza ait yüklü kadranları ele almanın bir yoludur. Sistem, bir pazar yerinin sahip olabileceği maksimum slot sayısını belirler. Wear OS 6'da bu sınır 1'dir.

Saat yüzü güncellenirken veya kaldırılırken işlem yapılacak saat yüzünü tanımlamak için slotId kullanılır.

Kadranları listeleme

Yüklü saat yüzlerinin listesini görmek için listWatchFaces() komutunu kullanın:

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")
WatchFacePush.kt

Bu sayede, yuvanın kullanılabilir olup olmadığını veya başka bir kadran eklemek için mevcut kadranın değiştirilmesi gerekip gerekmediğini belirleyebilirsiniz. Bu listede, yüklü kadranla ilgili ayrıntılar da yer alır. Örneğin, belirli bir saat yüzü paketinin yüklü olup olmadığını kontrol etmek için:

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

Kadran ekleme

listWatchFaces yanıtında belirtildiği gibi uygun slotlar varsa addWatchFace() yöntemi kullanılmalıdır:

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: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}
WatchFacePush.kt

Kadranı güncelleme

Kadran güncelleme, belirli bir yuvanın içeriğini yeni bir paketle değiştirmenize olanak tanır. Bu işlem, aynı kadranı daha yeni bir sürüme yükseltmek veya kadranı tamamen başka bir kadranla değiştirmek olabilir.

// 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
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}
WatchFacePush.kt

Saat yüzünü kaldırma

Bir saat yüzünü kaldırmak için:

// Remove the com.example.watchfacepush.green watch face.
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}
WatchFacePush.kt

Bu yaklaşım, saat yüzünüzün her zaman sistem saat yüzü seçicisinde bulunabileceği anlamına gelir. Logonuzu öne çıkarabilir, hatta telefonda Marketplace uygulamanızı başlatacak bir düğme ekleyebilirsiniz.

Saat yüzünüzün etkin olup olmadığını kontrol etme

Pazar yerinizde etkin kadranın ayarlanıp ayarlanmadığını belirlemek, kullanıcının sorunsuz bir deneyim yaşamasını sağlamak için önemlidir: Pazar yerinde etkin kadran ayarlanmışsa kullanıcı başka bir kadran seçmek isterse bu değişikliğin geçerli olması için mevcut kadranı pazar yeri uygulaması üzerinden değiştirmesi yeterlidir. Ancak pazar yerinde etkin kadran ayarı yoksa telefon uygulaması, kullanıcıya daha fazla rehberlik sunmalıdır. Bu kullanıcı deneyiminin nasıl ele alınacağıyla ilgili daha fazla bilgi için telefon uygulaması bölümüne bakın.

Pazar yerinde etkin kadranın ayarlanıp ayarlanmadığını belirlemek için aşağıdaki mantığı kullanın:

suspend fun hasActiveWatchFace() = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }
WatchFacePush.kt

Varsayılan bir kadran sağlama

Kadranı cihaza gönderme özelliği, pazar yeri uygulamanız yüklendiğinde varsayılan bir kadranı yükleme olanağı sunar. Bu işlem, söz konusu varsayılan kadranı etkin olarak ayarlamaz (bkz. etkin kadranı ayarlama) ancak kadranınızı sistem kadran seçicisinde kullanılabilir hâle getirir.

Bu özelliği kullanmak için:

1. Wear OS uygulama derlemenizde, varsayılan saat yüzünü şu yola ekleyin: assets/default_watchface.apk

2. AndroidManifest.xml dosyanıza aşağıdaki girişi ekleyin.

   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   AndroidManifest.xml

Etkin kadranı ayarlama

Watch Face Push, Marketplace uygulamasının etkin kadranı ayarlamasına olanak tanır.

Bu, özellikle mevcut etkin kadranın Marketplace'e ait olmadığı durumlarda uygulamanın etkin kadranı Marketplace'e ait bir kadran olarak ayarlayabileceği anlamına gelir. Pazar yerinde etkin kadran zaten varsa bu kadranı başka bir kadranla değiştirmek için updateWatchFace çağrısı yapılarak kadran yuvasının içeriği başka bir kadranla değiştirilir.

Etkin kadranı ayarlamak iki aşamalı bir işlemdir:

1. Etkin kadranı ayarlamak için gereken Android iznini alın.
2. setWatchFaceAsActive yöntemini çağırın.

Etkin kadranı ayarlamak için izin alma

Gerekli izin SET_PUSHED_WATCH_FACE_AS_ACTIVE'dır ve manifest dosyanıza eklenmelidir:

<!-- Required to be able to call the setWatchFaceAsActive() method. -->
<uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
AndroidManifest.xml

Bu bir çalışma zamanı izni olduğundan uygulamanız, uygulama çalışırken kullanıcıdan bu izni istemelidir (bu konuda yardımcı olması için Accompanist kitaplığını kullanabilirsiniz).

Kadranı etkin olarak ayarlama

İzin verildikten sonra, etkin olması gereken saat yüzünün yuva kimliğinde setWatchFaceAsActive işlevini çağırın.

Bu yöntem kullanıldıktan sonra telefon uygulamanız, etkin saat yüzünün manuel olarak nasıl ayarlanacağı konusunda yol gösterici bilgiler sunmalıdır.

Kadranınızın APK'sından ek meta veriler okuma

WatchFaceSlot nesnesi, kadranınızda belirtebileceğiniz ek bilgileri edinme olanağı da sunar.

Bu özellik, özellikle aynı saat yüzünün küçük varyantlarına sahip olduğunuz senaryolarda yararlı olabilir. Örneğin, aşağıdaki gibi bir saat yüzünüz olabilir:

• Paket adı: com.myapp.watchfacepush.mywatchface
• Paket sürümü: 1.0.0

Ancak bu saat yüzü, neredeyse tamamen aynı olan ancak farklı varsayılan renklere (kırmızı, sarı, yeşil ve mavi) sahip dört farklı APK olarak sunulabilir. Bu renkler, Saat Kadranı Formatı XML'sinde ColorConfiguration olarak ayarlanır.

Bu küçük değişiklik, dört APK'nın her birine yansıtılır:

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

Özel bir özellik kullanmak, uygulamanızın bu varyantlardan hangisinin yüklendiğini belirlemesine olanak tanır:

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")
WatchFacePush.kt

Dikkat edilmesi gereken noktalar

Uygulamanızda kadranı cihaza gönderme özelliğini uygularken dikkat etmeniz gereken önemli noktalar arasında güç tüketimine odaklanma, önbelleğe alma, paketlenmiş kadranları güncelleme ve temsili bir varsayılan kadran sağlama yer alır.

Güç

Wear OS'te çalışan tüm uygulamalar için önemli bir husus güç tüketimidir. Marketplace uygulamanızın Wear OS bileşeni için:

1. Uygulamanız, mümkün olduğunca az ve seyrek çalışmalıdır (kullanıcı doğrudan etkileşimde bulunmadığı sürece). Bu kapsamda:
   • Telefon uygulamasından uygulamayı uyandırmayı en aza indirme
   • WorkManager işlerinin çalıştırılmasını en aza indirme
2. Analytics raporlarını, kol saati şarj olurken çalışacak şekilde planlayın:
   1. Wear OS uygulamasından veya diğer metriklerden kullanım istatistiklerini bildirmek istiyorsanız requiresCharging kısıtlamasıyla WorkManager'ı kullanın.
3. Güncellemeleri, kol saati şarj olurken ve kablosuz ağ kullanırken yapılacak şekilde planlama:
   1. Yüklü kadranların sürümlerini kontrol edip otomatik olarak güncelleyebilirsiniz. Yine requiresCharging kısıtlamasını ve requiresNetworkType için UNMETERED ağ türünü kullanın.
   2. Şarjdayken cihazın kablosuz ağa erişimi olabilir. Güncellenen APK'ları hızlıca indirmek için Wi-Fi isteyin ve işlem tamamlandığında ağı serbest bırakın.
   3. Bu kılavuz, pazar yerinin günün saat yüzünü sunduğu durumlarda da geçerlidir. Bu saat yüzünü, kol saati şarj olurken önceden indirin.
4. Etkin kadranı kontrol etmek için iş planlamayın:
   1. Pazar yerinizin etkin bir saat yüzü olup olmadığını ve hangi saat yüzünün etkin olduğunu düzenli olarak kontrol etmek pilin boşalmasına neden olur. Bu yaklaşımdan kaçının.
5. Saatte bildirimleri kullanmayın:
   1. Uygulamanız bildirimleri kullanıyorsa bunları telefona odaklayın. Kullanıcı işlemi, yolculuğa devam etmek için telefon uygulamasını açar. setLocalOnly kullanarak bildirimlerin saat uygulamasına aktarılmamasını sağlayacak şekilde yapılandırın.

Önbelleğe alınıyor

Standart pazar yeri örneğinde, saat yüzleri telefondan kol saatine aktarılır. Bu bağlantı genellikle Bluetooth bağlantısıdır ve oldukça yavaş olabilir.

Hem daha iyi bir kullanıcı deneyimi sunmak hem de yeniden iletim gücünden tasarruf etmek için Wear OS cihazında birkaç APK'yı depolayacak küçük bir önbellek uygulayabilirsiniz.

Kullanıcı başka bir saat yüzü denedikten sonra daha önce seçtiği saat yüzüne geri dönmeye karar verirse bu işlem neredeyse anında gerçekleşir.

Benzer şekilde, bu özellik günün kadranı için önbelleğe alma veya Wear OS cihaz şarj olurken kadranların indirildiği benzer düzenler için de kullanılabilir.

Paketlenmiş kadranları güncelleme

Uygulamanız, daha önce açıklandığı gibi varsayılan bir kadran öğesi içerebilir. Bu saat yüzü, pazar yeri uygulamanız yüklendiğinde sisteme yüklenir. Ancak pazar yeri uygulamanızın güncellenmesiyle birlikte daha yeni bir sürüm paketlenirse saat yüzü güncellenmez.

Bu durumu ele almak için pazar yeri uygulamanız MY_PACKAGE_REPLACED yayın işlemini dinlemeli ve paket öğelerinden paketlenmiş bir kadranı güncelleme ihtiyacını kontrol etmelidir.

Temsili varsayılan kadran

Varsayılan bir kadran, kullanıcılarınızın pazar yerinizi keşfetmesine ve kullanmasına yardımcı olmanın harika bir yoludur. Kadran, pazar yerinizle birlikte yüklenir. Böylece kullanıcılar, kadran galerisinde bu kadranı bulabilir.

Varsayılan saat yüzleriyle çalışırken dikkat edilmesi gereken bazı noktalar:

• Kullanıcı, Marketplace uygulamanızdan bir kadranı kaldırmayı seçerse removeWatchFace kullanmayın. Bunun yerine, bu durumda updateWatchFace kullanarak kadranı varsayılan kadran olarak geri döndürün. Bu, kullanıcıların kadranınızı bulmasına ve galeriden ayarlamasına yardımcı olur.
• Varsayılan kadranı logonuz ve temalandırmanızla basit ve anında tanınabilir hale getirin. Bu sayede kullanıcılar, kadran galerisinde kadranınızı bulabilir.

• Telefon uygulamasını açmak için varsayılan saat yüzüne bir düğme ekleyin. Bu işlem iki aşamada gerçekleştirilebilir:

  1. Wear OS uygulamasını kullanarak bir amaç başlatmak için kadranına Launch öğesi ekleyin. Örneğin:

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

  2. LaunchOnPhoneActivity bölümünde, RemoteActivityHelper simgesini kullanarak telefon uygulamasını başlatın.