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

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

डेटा सोर्स की सेवा, SuspendingComplicationDataSourceService को बढ़ाकर, वॉच फ़ेस को सीधे काम की जानकारी उपलब्ध कराती है.

शुरू करना

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

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

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

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

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()

    // ...
}MyComplicationDataSourceService.kt

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

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

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

इसके अलावा, 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>AndroidManifest.xml

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

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

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>AndroidManifest.xml

गतिविधि, उस कॉम्प्लिकेशन स्लॉट की जानकारी पा सकती है जिसे वह कॉन्फ़िगर कर रही है. यह जानकारी, गतिविधि के 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)ConfigurationActivity.kt

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

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()ConfigurationActivity.kt

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

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

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

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

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

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

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()

    // ...
}MyTimelineComplicationDataSourceService.kt

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

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

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

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

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

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

कभी-कभी डाइनैमिक वैल्यू उपलब्ध नहीं होती: ऐसा तब होता है, जब डिवाइस को कलाई से हटाया जाता है. इन स्थितियों में, प्लैटफ़ॉर्म, NoDataComplicationData's प्लेसहोल्डर फ़ील्ड में, डाइनैमिक वैल्यू के अमान्य होने पर फ़ॉलबैक फ़ील्ड की वैल्यू का इस्तेमाल करता है.
डाइनैमिक वैल्यू कभी उपलब्ध नहीं होती: ऐसा तब होता है, जब डिवाइस Wear OS 4 के पुराने वर्शन पर चल रहा हो. इस स्थिति में, प्लैटफ़ॉर्म, साथी डिवाइस के फ़ॉलबैक फ़ील्ड का इस्तेमाल करता है, जैसे getFallbackValue().

टाइप और फ़ील्ड

Wear OS के सैंपल का कलेक्शन