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

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 सिस्टम, सेवा देने वाली कंपनियों की सेवाओं से जुड़ सके.

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

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

<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 (पांच मिनट) की वैल्यू का इस्तेमाल करना होगा. यह सिस्टम की ओर से लागू की गई, अपडेट करने की कम से कम अवधि है. इससे डिवाइस की बैटरी लाइफ़ बनी रहती है. इसके अलावा, ध्यान रखें कि डिवाइस के ऐंबियंट मोड में होने या उसे न पहनने पर, अपडेट के अनुरोध कम बार किए जाते हैं.

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

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

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

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

<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 लाइब्रेरी पर आधारित होती हैं.

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