स्मार्टवॉच की होम स्क्रीन पर सूचनाएं भेजने की सुविधा के लिए, Wear OS ऐप्लिकेशन को कॉन्फ़िगर करना

वॉच फ़ेस पुश की सुविधा की मदद से, आपका ऐप्लिकेशन Wear OS डिवाइस पर स्मार्टवॉच की होम स्क्रीन को मैनेज कर सकता है. इसमें वॉच फ़ेस जोड़ना, अपडेट करना, और हटाना शामिल है. साथ ही, इसमें मौजूदा वॉच फ़ेस सेट करना भी शामिल है. Watch Face Push API का इस्तेमाल करने के लिए, Wear OS ऐप्लिकेशन को कॉन्फ़िगर करें.

सेटअप

अपनी build.gradle.kts फ़ाइल में, androidx.wear.watchfacepush:watchfacepush डिपेंडेंसी शामिल करें.

अपनी AndroidManifest.xml में यह जोड़ें:

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

मैनेजर इंस्टेंस का रेफ़रंस पाना

WatchFacePushManager का इंस्टेंस पाएं:

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

WatchFacePushManager, Watch Face Push के साथ इंटरैक्ट करने के सभी तरीकों को ऐक्सेस करने की सुविधा देता है.

स्लॉट के साथ काम करना

वॉच फ़ेस पुश के साथ काम करते समय, स्लॉट एक मुख्य कॉन्सेप्ट है. स्लॉट, इंस्टॉल किए गए उन वॉच फ़ेस को ऐक्सेस करने का तरीका है जो आपके ऐप्लिकेशन से जुड़े हैं. सिस्टम, मार्केटप्लेस के लिए ज़्यादा से ज़्यादा स्लॉट सेट करता है. Wear OS 6 के लिए, यह सीमा 1 है.

वॉच फ़ेस को अपडेट या हटाने के दौरान, slotId का इस्तेमाल वॉच फ़ेस की पहचान करने के लिए किया जाता है, ताकि उस पर कार्रवाई की जा सके.

वॉच फ़ेस की सूची बनाना

इंस्टॉल की गई स्मार्ट वॉच की होम स्क्रीन की सूची बनाने के लिए, listWatchFaces() का इस्तेमाल करें:

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

इससे यह पता चलता है कि स्लॉट उपलब्ध है या किसी दूसरी होम स्क्रीन को जोड़ने के लिए, मौजूदा होम स्क्रीन को बदलना होगा. इस सूची में, इंस्टॉल किए गए वॉच फ़ेस के बारे में भी जानकारी मिलती है. उदाहरण के लिए, यह देखने के लिए कि स्मार्टवॉच की होम स्क्रीन का कोई पैकेज इंस्टॉल किया गया है या नहीं:

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

वॉच फ़ेस जोड़ना

अगर listWatchFaces रिस्पॉन्स के मुताबिक स्लॉट उपलब्ध हैं, तो addWatchFace() तरीके का इस्तेमाल किया जाना चाहिए:

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

ध्यान दें: slotId वैल्यू को सेव न करें या उन्हें स्थायी के तौर पर न मानें. ऐसा हो सकता है कि आपके ऐप्लिकेशन के बाहर, वॉच फ़ेस की स्थिति बदल जाए. उदाहरण के लिए, कोई उपयोगकर्ता सिस्टम यूज़र इंटरफ़ेस (यूआई) के ज़रिए आपके वॉच फ़ेस को अनइंस्टॉल कर सकता है. स्लॉट पर आधारित कोई भी कार्रवाई करने से पहले, हमेशा मौजूदा स्थिति का पता लगाएं.

वॉच फ़ेस अपडेट करना

वॉच फ़ेस अपडेट करने पर, किसी स्लॉट के कॉन्टेंट को नए पैकेज से बदला जा सकता है. ऐसा हो सकता है कि आपने उसी वॉच फ़ेस को नए वर्शन में अपग्रेड किया हो या उसे किसी दूसरे वॉच फ़ेस से बदल दिया हो.

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

स्मार्टवॉच की होम स्क्रीन हटाना

स्मार्ट वॉच की होम स्क्रीन हटाने के लिए:

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

इस तरीके का मतलब है कि आपके वॉच फ़ेस को सिस्टम वॉच फ़ेस पिकर में हमेशा देखा जा सकता है. इसमें अपने लोगो को प्रमुखता से दिखाया जा सकता है. साथ ही, फ़ोन पर Marketplace ऐप्लिकेशन लॉन्च करने के लिए बटन भी दिखाया जा सकता है.

देखें कि आपका वॉच फ़ेस चालू है या नहीं

यह पता लगाना ज़रूरी है कि आपके मार्केटप्लेस में स्मार्टवॉच की होम स्क्रीन सेट है या नहीं. इससे उपयोगकर्ता को बेहतर अनुभव मिलता है: अगर मार्केटप्लेस में स्मार्टवॉच की होम स्क्रीन पहले से सेट है, तो उपयोगकर्ता को कोई दूसरी होम स्क्रीन चुनने के लिए, मार्केटप्लेस ऐप्लिकेशन के ज़रिए मौजूदा होम स्क्रीन को बदलना होगा. हालांकि, अगर मार्केटप्लेस में स्मार्टवॉच की होम स्क्रीन सेट नहीं है, तो फ़ोन ऐप्लिकेशन को उपयोगकर्ता को ज़्यादा जानकारी देनी होगी. उपयोगकर्ता अनुभव को मैनेज करने के तरीके के बारे में ज़्यादा जानने के लिए, फ़ोन ऐप्लिकेशन वाला सेक्शन देखें.

मार्केटप्लेस ने मौजूदा वॉच फ़ेस सेट किया है या नहीं, यह पता लगाने के लिए इस लॉजिक का इस्तेमाल करें:

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

चेतावनी: updateWatchFace() को कॉल करने के बाद, तुरंत isWatchFaceActive() को कॉल न करें. इससे अनचाहे नतीजे मिल सकते हैं. वॉच फ़ेस बदलने की प्रोसेस पूरी होने में थोड़ा समय लग सकता है.

इसके बजाय, पहले यह तय करें कि कॉल करने वाले ऐप्लिकेशन के पास, चालू वॉच फ़ेस का रेफ़रंस है या नहीं. जैसा कि पिछले स्निपेट में दिखाया गया है. इसके बाद, फिर updateWatchFace() को कॉल करें. अगर updateWatchFace() पूरा हो जाता है, तो इसका मतलब है कि आपके ऐप्लिकेशन के पास अब भी चालू वॉच फ़ेस को कंट्रोल करने का ऐक्सेस है.

डिफ़ॉल्ट वॉच फ़ेस उपलब्ध कराना

वॉच फ़ेस पुश की सुविधा की मदद से, मार्केटप्लेस ऐप्लिकेशन इंस्टॉल होने पर डिफ़ॉल्ट वॉच फ़ेस इंस्टॉल किया जा सकता है. इससे डिफ़ॉल्ट वॉच फ़ेस अपने-आप चालू नहीं होता. इसके लिए, आपको वॉच फ़ेस चालू करने की सेटिंग में जाना होगा. हालांकि, इससे आपका वॉच फ़ेस, सिस्टम के वॉच फ़ेस पिकर में उपलब्ध हो जाता है.

इस सुविधा का इस्तेमाल करने के लिए:

Wear OS ऐप्लिकेशन के बिल्ड में, डिफ़ॉल्ट वॉच फ़ेस को इस पाथ में शामिल करें: assets/default_watchface.apk

अपनी AndroidManifest.xml में यह एंट्री जोड़ें

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

ध्यान दें: आम तौर पर, बिल्ड पैटर्न में प्री-बिल्ड चरण के तौर पर, अपने ऐप्लिकेशन के पूरे बिल्ड के हिस्से के तौर पर default_watchface.apk को बिल्ड करना शामिल होता है. इसका इस्तेमाल, पुष्टि करने वाले टोकन की मेनिफ़ेस्ट वैल्यू को भरने के लिए किया जा सकता है. इसके लिए, डिफ़ॉल्ट वॉच फ़ेस बनाने की प्रोसेस में, एक अतिरिक्त Android रिसॉर्स एक्सएमएल फ़ाइल आउटपुट करें. साथ ही, उस रिसॉर्स पाथ को अपने मुख्य ऐप्लिकेशन में अतिरिक्त रिसॉर्स पाथ के तौर पर शामिल करें. यह तरीका, बिल्ड प्रोसेस के दौरान मेनिफ़ेस्ट फ़ाइल में बदलाव करने की कोशिश करने से ज़्यादा आसान है.

स्मार्टवॉच के मौजूदा वॉच फ़ेस को सेट करना

वॉच फ़ेस पुश की सुविधा की मदद से, Marketplace ऐप्लिकेशन को मौजूदा वॉच फ़ेस सेट करने का विकल्प मिलता है.

इसका मतलब है कि अगर मौजूदा वॉच फ़ेस Marketplace से नहीं है, तो ऐप्लिकेशन, Marketplace से जुड़े किसी वॉच फ़ेस को मौजूदा वॉच फ़ेस के तौर पर सेट कर सकता है. ध्यान दें कि अगर मार्केटप्लेस में पहले से ही कोई वॉच फ़ेस मौजूद है, तो उसे दूसरे वॉच फ़ेस में बदलने के लिए, updateWatchFace को कॉल किया जाता है. इससे वॉच फ़ेस स्लॉट के कॉन्टेंट को दूसरे वॉच फ़ेस से बदला जा सकता है.

वॉच फ़ेस को ऐक्टिव के तौर पर सेट करने की प्रोसेस में दो चरण होते हैं:

मौजूदा वॉच फ़ेस को सेट करने के लिए, Android की ज़रूरी अनुमति पाएं.
setWatchFaceAsActive तरीके को कॉल करें.

स्मार्टवॉच के मौजूदा वॉच फ़ेस को सेट करने की अनुमतियां पाना

इसके लिए, SET_PUSHED_WATCH_FACE_AS_ACTIVE अनुमति ज़रूरी है. इसे आपके मेनिफ़ेस्ट में जोड़ा जाना चाहिए:

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

यह रनटाइम की अनुमति है. इसलिए, जब आपका ऐप्लिकेशन चलता है, तब उसे उपयोगकर्ता से इस अनुमति का अनुरोध करना होगा. इसके लिए, Accompanist लाइब्रेरी का इस्तेमाल किया जा सकता है.

वॉच फ़ेस को स्मार्टवॉच के मौजूदा वॉच फ़ेस के तौर पर सेट करें

अनुमति मिल जाने के बाद, उस वॉच फ़ेस के स्लॉट आईडी पर setWatchFaceAsActive को कॉल करें जिसे चालू करना है.

इस सुविधा का इस्तेमाल करने के बाद, आपके फ़ोन ऐप्लिकेशन को यह जानकारी देनी चाहिए कि मौजूदा वॉच फ़ेस को मैन्युअल तरीके से कैसे सेट किया जाए.

स्मार्ट वॉच की होम स्क्रीन के APK से अतिरिक्त मेटाडेटा पढ़ना

WatchFaceSlot ऑब्जेक्ट से, आपको ऐसी अतिरिक्त जानकारी भी मिलती है जिसे आपको अपनी होम स्क्रीन पर दिखाना होता है.

यह सुविधा खास तौर पर उन स्थितियों में काम आ सकती है जहां आपके पास एक ही वॉच फ़ेस के कुछ अलग-अलग वर्शन हों. उदाहरण के लिए, आपके पास इस तरह से वॉच फ़ेस तय करने का विकल्प होता है:

पैकेज का नाम: com.myapp.watchfacepush.mywatchface
पैकेज का वर्शन: 1.0.0

हालांकि, यह वॉच फ़ेस चार अलग-अलग APK के तौर पर उपलब्ध हो सकता है. इनमें से सभी APK लगभग एक जैसे होते हैं, लेकिन इनके डिफ़ॉल्ट रंग अलग-अलग होते हैं: लाल, पीला, हरा और नीला. इन्हें Watch Face Format वाले एक्सएमएल में ColorConfiguration में सेट किया जाता है.

इसके बाद, यह मामूली अंतर इन चारों APK में दिखता है:

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

कस्टम प्रॉपर्टी का इस्तेमाल करके, आपका ऐप्लिकेशन यह तय कर सकता है कि इनमें से कौनसा वैरिएंट इंस्टॉल किया गया है:

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

ज़रूरी बातें

अपने ऐप्लिकेशन में वॉच फ़ेस पुश करने की सुविधा लागू करते समय, इन बातों का ध्यान रखना ज़रूरी है: बैटरी की खपत, कैश मेमोरी, बंडल किए गए वॉच फ़ेस अपडेट करना, और डिफ़ॉल्ट वॉच फ़ेस उपलब्ध कराना.

ताकत

Wear OS पर काम करने वाले किसी भी ऐप्लिकेशन के लिए, बैटरी की खपत एक अहम पहलू है. मार्केटप्लेस ऐप्लिकेशन के Wear OS कॉम्पोनेंट के लिए:

आपका ऐप्लिकेशन कम से कम और कभी-कभी ही चलना चाहिए. हालांकि, अगर उपयोगकर्ता सीधे तौर पर ऐप्लिकेशन के साथ इंटरैक्ट कर रहा है, तो ऐसा नहीं होना चाहिए. इसमें ये शामिल हैं:
- फ़ोन ऐप्लिकेशन से ऐप्लिकेशन को कम से कम बार चालू करना
- WorkManager के जॉब को कम से कम चलाना
स्मार्टवॉच चार्ज होने के दौरान, किसी भी Analytics रिपोर्टिंग को शेड्यूल करें:
1. अगर आपको Wear OS ऐप्लिकेशन के इस्तेमाल के आंकड़े या किसी अन्य मेट्रिक की रिपोर्ट करनी है, तो requiresCharging कंस्ट्रेंट के साथ WorkManager का इस्तेमाल करें.
अपडेट को तब शेड्यूल करें, जब स्मार्टवॉच चार्ज हो रही हो और वाई-फ़ाई का इस्तेमाल किया जा रहा हो:
1. आपके पास इंस्टॉल किए गए वॉच फ़ेस के वर्शन देखने और उन्हें अपने-आप अपडेट करने का विकल्प होता है. requiresNetworkType के लिए, requiresCharging कंस्ट्रेंट और UNMETERED नेटवर्क टाइप का फिर से इस्तेमाल करें.
2. चार्जिंग के दौरान, डिवाइस के वाई-फ़ाई से कनेक्ट होने की संभावना ज़्यादा होती है. अपडेट किए गए APK को तुरंत डाउनलोड करने के लिए, वाई-फ़ाई का अनुरोध करें. इसके बाद, डाउनलोड हो जाने पर नेटवर्क को रिलीज़ करें.
3. मार्केटप्लेस पर दिन के हिसाब से वॉच फ़ेस उपलब्ध हो सकते हैं. ऐसे में, वॉच चार्ज करते समय इन्हें पहले से डाउनलोड कर लें.
ऐक्टिव वॉच फ़ेस की जांच करने के लिए, जॉब शेड्यूल न करें:
1. समय-समय पर यह जांच करना कि मार्केटप्लेस पर अब भी स्मार्टवॉच की होम स्क्रीन चालू है या नहीं और वह कौनसी होम स्क्रीन है, इससे बैटरी की खपत होती है. इस तरीके का इस्तेमाल न करें.
स्मार्टवॉच पर सूचनाएं पाने की सुविधा का इस्तेमाल न करें:
1. अगर आपका ऐप्लिकेशन सूचनाएं भेजता है, तो उन्हें फ़ोन पर भेजें. इससे उपयोगकर्ता, फ़ोन ऐप्लिकेशन खोलकर अपनी यात्रा जारी रख पाएगा. setLocalOnly का इस्तेमाल करके, सूचनाओं को स्मार्टवॉच ऐप्लिकेशन पर न भेजने के लिए कॉन्फ़िगर करें.

संचय कर रहा है

कैननिकल मार्केटप्लेस के उदाहरण में, वॉच फ़ेस को फ़ोन से स्मार्टवॉच में ट्रांसफ़र किया जाता है. आम तौर पर, यह कनेक्शन ब्लूटूथ कनेक्शन होता है, जो काफ़ी धीमा हो सकता है.

उपयोगकर्ताओं को बेहतर अनुभव देने और रीट्रांसमिशन पावर को बचाने के लिए, Wear OS डिवाइस में छोटी कैश मेमोरी लागू करें. इससे कुछ APK सेव किए जा सकेंगे.

अगर कोई उपयोगकर्ता किसी दूसरे वॉच फ़ेस को आज़माता है, लेकिन बाद में उसे पहले से चुना गया वॉच फ़ेस वापस चाहिए, तो यह कार्रवाई तुरंत हो जाती है.

इसी तरह, इसका इस्तेमाल दिन के हिसाब से स्मार्टवॉच की होम स्क्रीन के लिए प्रीकैशिंग के लिए किया जा सकता है. इसके अलावा, इसका इस्तेमाल ऐसी ही अन्य स्कीम के लिए भी किया जा सकता है. इन स्कीम में, Wear OS डिवाइस चार्ज होने के दौरान स्मार्टवॉच की होम स्क्रीन डाउनलोड की जाती हैं.

बंडल किए गए वॉच फ़ेस अपडेट करना

आपके ऐप्लिकेशन में, डिफ़ॉल्ट वॉच फ़ेस ऐसेट शामिल हो सकती है. इसके बारे में पहले बताया जा चुका है. यह जानना ज़रूरी है कि जब आपका Marketplace ऐप्लिकेशन इंस्टॉल किया जाता है, तब यह वॉच फ़ेस सिस्टम में इंस्टॉल हो जाता है. हालांकि, अगर आपके Marketplace ऐप्लिकेशन के किसी अपडेट के साथ नया वर्शन बंडल किया जाता है, तो वॉच फ़ेस अपडेट नहीं होता.

इस स्थिति को मैनेज करने के लिए, आपके मार्केटप्लेस ऐप्लिकेशन को MY_PACKAGE_REPLACED ब्रॉडकास्ट ऐक्शन के लिए सुनना चाहिए. साथ ही, पैकेज की ऐसेट से बंडल किए गए किसी भी वॉच फ़ेस को अपडेट करने की ज़रूरत है या नहीं, यह देखना चाहिए.

डिफ़ॉल्ट होम स्क्रीन की प्रतिनिधि इमेज

डिफ़ॉल्ट वॉच फ़ेस, लोगों को आपके मार्केटप्लेस को खोजने और उसका इस्तेमाल करने में मदद करता है: जब आपका मार्केटप्लेस इंस्टॉल होता है, तब वॉच फ़ेस इंस्टॉल हो जाता है. इसलिए, लोग इसे वॉच फ़ेस गैलरी में ढूंढ सकते हैं.

डिफ़ॉल्ट वॉच फ़ेस इस्तेमाल करते समय इन बातों का ध्यान रखें:

अगर उपयोगकर्ता, आपके मार्केटप्लेस ऐप्लिकेशन से स्मार्ट वॉच की होम स्क्रीन को अनइंस्टॉल करने का विकल्प चुनता है, तो removeWatchFace का इस्तेमाल न करें. इसके बजाय, इस मामले में updateWatchFace का इस्तेमाल करके, स्मार्ट वॉच की होम स्क्रीन को डिफ़ॉल्ट होम स्क्रीन पर वापस ले जाएं. इससे लोगों को आपकी स्मार्टवॉच की होम स्क्रीन ढूंढने और उसे गैलरी से सेट करने में मदद मिलती है.
डिफ़ॉल्ट वॉच फ़ेस को आसान बनाएं. साथ ही, अपने लोगो और थीम की मदद से उसे तुरंत पहचाने जाने लायक बनाएं. इससे लोगों को स्मार्टवॉच की होम स्क्रीन गैलरी में इसे ढूंढने में मदद मिलती है.
फ़ोन ऐप्लिकेशन खोलने के लिए, डिफ़ॉल्ट वॉच फ़ेस में एक बटन जोड़ें. इसे दो चरणों में पूरा किया जा सकता है:
1. Wear OS ऐप्लिकेशन का इस्तेमाल करके इंटेंट लॉन्च करने के लिए, स्मार्टवॉच की होम स्क्रीन पर Launch एलिमेंट जोड़ें. उदाहरण के लिए:
  
  <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />
2. LaunchOnPhoneActivity में, RemoteActivityHelper का इस्तेमाल करके फ़ोन ऐप्लिकेशन लॉन्च करें.