কমপ্লিকেশনে ডেটা এক্সপোজ করা

কমপ্লিকেশন ডেটা সোর্স, ওয়াচ ফেসে তথ্য দেখায় কমপ্লিকেশন, টেক্সট, ছবি ও সংখ্যা প্রদান করে যা ওয়াচ ফেস রেন্ডার করতে পারে।

ডেটা সোর্স পরিষেবা 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()

    // ...
}
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 (৫ মিনিট) মান ব্যবহার করতে হবে, যা হল সিস্টেমের প্রয়োগ করা সর্বনিম্ন আপডেট পিরিয়ড। এটি ডিভাইসের ব্যাটারির আয়ু বাঁচানোর জন্য করা হয়। এছাড়াও, মনে রাখবেন যে ডিভাইস অ্যাম্বিয়েন্ট মোডে থাকলে বা পরা না থাকলে আপডেট করার অনুরোধ কম আসে।

কনফিগারেশন অ্যাক্টিভিটি যোগ করা

প্রয়োজন হলে, ডেটা সোর্সে এমন কনফিগারেশন অ্যাক্টিভিটি থাকতে পারে যা ব্যবহারকারী জটিলতা বাছাইকারী থেকে সেই নির্দিষ্ট ডেটা সোর্স বেছে নিলে তাকে দেখানো হয়। যেমন, একটি ওয়ার্ল্ড ক্লক ডেটা সোর্সে এমন কনফিগারেশন অ্যাক্টিভিটি থাকতে পারে যা ব্যবহারকারীকে দেখানোর জন্য শহর বা টাইম জোন বেছে নিতে দেয়।

উদাহরণ ম্যানিফেস্টে 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>
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().

সম্পর্কিত রিসোর্স