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

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

ডেটা সোর্স পরিষেবা 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 (৫ মিনিট) মান ব্যবহার করতে হবে, যা সিস্টেম দ্বারা প্রয়োগ করা ন্যূনতম আপডেট সময়কাল, যাতে ডিভাইসের ব্যাটারি লাইফ সংরক্ষণ করা যায়। এছাড়াও, মনে রাখবেন যে ডিভাইস অ্যাম্বিয়েন্ট মোডে থাকলে বা পরা না থাকলে আপডেট করার অনুরোধ কম আসে।

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

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

উদাহরণ ম্যানিফেস্টে 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 লাইব্রেরির উপর ভিত্তি করে তৈরি।

কিছু পরিস্থিতিতে, প্ল্যাটফর্ম ডায়নামিক ভ্যালু মূল্যায়ন করতে পারে না: