Android स्मार्टवॉच के डेटा को Android के विजेट से जोड़ें

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

डेटा सोर्स की सेवा, SuspendingComplicationDataSourceService को एक्सटेंड करती है, ताकि सीधे वॉच फ़ेस पर काम की जानकारी दिखाई जा सके.

शुरू करना

अपने ऐप्लिकेशन मॉड्यूल में यह डिपेंडेंसी जोड़ें: 

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

डेटा सोर्स सेवा बनाना

जब विजेट के डेटा की ज़रूरत होती है, तब Wear OS सिस्टम आपके डेटा सोर्स को अपडेट करने के अनुरोध भेजता है. अपडेट के अनुरोधों का जवाब देने के लिए, आपके डेटा सोर्स को SuspendingComplicationDataSourceService क्लास के onComplicationRequest() तरीके को लागू करना होगा.

Wear OS सिस्टम, onComplicationRequest() को तब कॉल करता है, जब उसे आपके सोर्स से डेटा की ज़रूरत होती है. उदाहरण के लिए, जब आपके डेटा सोर्स का इस्तेमाल करने वाली कोई जटिलता चालू हो जाती है या जब तय समय बीत जाता है.

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

नीचे दिया गया कोड स्निपेट, इसे लागू करने का एक उदाहरण दिखाता है:

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}

मेनिफ़ेस्ट में एलान और अनुमतियां

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

अपने ऐप्लिकेशन के मेनिफ़ेस्ट में, सेवा का एलान करें और अपडेट के अनुरोध की कार्रवाई का इंटेंट फ़िल्टर जोड़ें. मेनिफ़ेस्ट को सेवा की सुरक्षा भी करनी चाहिए. इसके लिए, BIND_COMPLICATION_PROVIDER अनुमति जोड़नी होगी, ताकि यह पक्का किया जा सके कि सिर्फ़ Wear OS सिस्टम, सेवा देने वाली कंपनी की सेवाओं से जुड़ सके.

साथ ही, service एलिमेंट में android:icon एट्रिब्यूट शामिल करें, जो एक ही रंग का सफ़ेद आइकॉन उपलब्ध कराता है. हमारा सुझाव है कि आइकॉन के लिए, ड्रॉ करने लायक वेक्टर का इस्तेमाल करें. यह आइकॉन, डेटा सोर्स को दिखाता है और कॉम्प्लिकेशन पिकर में दिखता है.

यहां एक उदाहरण दिया गया है: 

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    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>

    <!-- Supported types should be comma-separated, for example: "SHORT_TEXT,SMALL_IMAGE" -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!-- Optionally, specify a configuration activity, where the user can configure your complication. -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>

मेटाडेटा एलिमेंट

अपनी मेनिफ़ेस्ट फ़ाइल में, इन मेटाडेटा एलिमेंट पर ध्यान दें:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": इससे पता चलता है कि डेटा सोर्स, किस तरह के कॉम्प्लिकेशन डेटा के साथ काम करता है.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": इससे यह तय होता है कि सिस्टम को डेटा के अपडेट के लिए कितनी बार जांच करनी चाहिए.

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

अगर आपने UPDATE_PERIOD_SECONDS को 0 पर सेट नहीं किया है, तो आपको कम से कम 300 (पांच मिनट) की वैल्यू का इस्तेमाल करना होगा. यह अपडेट की कम से कम अवधि है, जिसे सिस्टम लागू करता है. इससे डिवाइस की बैटरी लाइफ़ को बचाया जा सकता है. इसके अलावा, ध्यान रखें कि जब डिवाइस हमेशा चालू स्क्रीन मोड में होता है या उसे पहना नहीं जाता है, तब अपडेट के अनुरोध कम आते हैं.

कॉन्फ़िगरेशन गतिविधि जोड़ना

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

उदाहरण के तौर पर दिए गए मेनिफ़ेस्ट में, meta-data एलिमेंट शामिल है. इसमें PROVIDER_CONFIG_ACTION कुंजी है. इस एलिमेंट की वैल्यू, वह कार्रवाई है जिसका इस्तेमाल कॉन्फ़िगरेशन गतिविधि को लॉन्च करने के लिए किया जाता है.

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

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

गतिविधि, इंटेंट से कॉन्फ़िगर किए जा रहे स्मार्ट वॉच के विजेट के स्लॉट की जानकारी हासिल कर सकती है. इसके लिए, गतिविधि के onCreate() तरीके का इस्तेमाल किया जाता है: 

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)

कॉन्फ़िगरेशन गतिविधि, सेवा देने वाली कंपनी के पैकेज में ही होनी चाहिए. कॉन्फ़िगरेशन गतिविधि को RESULT_OK या RESULT_CANCELED दिखाना चाहिए, ताकि सिस्टम को यह बताया जा सके कि डेटा सोर्स को सेट किया जाना चाहिए या नहीं: 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

पुश अपडेट का इस्तेमाल करना

ऐप्लिकेशन के मेनिफ़ेस्ट में अपडेट का इंटरवल तय करने के बजाय, डाइनैमिक तौर पर अपडेट शुरू करने के लिए, ComplicationDataSourceUpdateRequester के इंस्टेंस का इस्तेमाल किया जा सकता है. अपडेट का अनुरोध करने के लिए, requestUpdate() पर कॉल करें.

चेतावनी: डिवाइस की बैटरी लाइफ़ बचाने के लिए, ComplicationDataSourceUpdateRequester के अपने इंस्टेंस से requestUpdate() को औसतन हर पांच मिनट से ज़्यादा बार कॉल न करें.

समय के हिसाब से वैल्यू उपलब्ध कराना

कुछ विजेट को ऐसी वैल्यू दिखानी होती है जो मौजूदा समय से जुड़ी हो. उदाहरण के लिए, मौजूदा तारीख, अगली मीटिंग शुरू होने में बचा समय या किसी दूसरे टाइम ज़ोन का समय.

वैल्यू को अप-टू-डेट रखने के लिए, हर सेकंड या मिनट में विजेट को अपडेट न करें. इसके बजाय, समय के हिसाब से बदलने वाले टेक्स्ट का इस्तेमाल करके, मौजूदा तारीख या समय के हिसाब से वैल्यू तय करें. इन क्लास की मदद से, समय के हिसाब से वैल्यू बनाई जा सकती हैं:

  • TimeFormatComplicationText - तारीख या समय की वैल्यू को फ़ॉर्मैट करता है.
  • TimeDifferenceComplicationText - तय किए गए समय तक, आगे या पीछे की ओर गिनती करता है.

टाइमलाइन का डेटा

पहले से तय समय पर वैल्यू का क्रम उपलब्ध कराने वाले कॉम्प्लिकेशन डेटा सोर्स के लिए, SuspendingTimelineComplicationDataSourceService का इस्तेमाल करें.

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

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}

SuspendingTimelineComplicationDataSourceService का व्यवहार इस तरह होता है:

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

डाइनैमिक वैल्यू उपलब्ध कराना

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

उदाहरण के तौर पर, फ़ील्ड में ये शामिल हैं GoalProgressComplicationData का डाइनैमिक वैल्यू फ़ील्ड, और DynamicComplicationText, जिसका इस्तेमाल किसी भी ComplicationText फ़ील्ड में किया जा सकता है. ये डाइनैमिक वैल्यू, androidx.wear.protolayout.expression लाइब्रेरी पर आधारित होती हैं.

कुछ मामलों में, प्लैटफ़ॉर्म डाइनैमिक वैल्यू का आकलन नहीं कर सकता: