داده ها را در معرض عوارض قرار دهید

برنامه‌های ارائه‌دهنده داده، اطلاعات را در معرض عوارض تماشای چهره قرار می‌دهند، فیلدهایی که حاوی متن، رشته‌ها، تصاویر و اعداد هستند.

یک سرویس ارائه دهنده داده، ComplicationProviderService را گسترش می دهد تا اطلاعات مفید را مستقیماً به صفحه ساعت ارائه دهد.

یک پروژه ارائه دهنده داده ایجاد کنید

برای ایجاد یک پروژه در Android Studio برای برنامه ارائه دهنده داده خود، مراحل زیر را انجام دهید:

  1. روی فایل > جدید > پروژه جدید کلیک کنید.
  2. در پنجره Project Template ، روی تب Wear OS کلیک کنید، No Activity را انتخاب کنید و روی Next کلیک کنید.
  3. در پنجره Configure Your Project ، نام پروژه خود را بگذارید، اطلاعات استاندارد پروژه را پر کنید و روی Finish کلیک کنید.
  4. Android Studio یک پروژه با یک ماژول برنامه برای ارائه دهنده داده شما ایجاد می کند. برای اطلاعات بیشتر درباره پروژه‌ها در Android Studio، به ایجاد پروژه مراجعه کنید.
  5. برنامه ارائه دهنده داده خود را با ایجاد یک کلاس جدید که BroadcastReceiver گسترش می دهد، شروع کنید. هدف آن کلاس گوش دادن به درخواست‌های به‌روزرسانی پیچیده از سیستم Wear OS است. علاوه بر این، یک کلاس جدید ایجاد کنید که ComplicationProviderService را گسترش دهد تا داده هایی را که توسط پیچیدگی های مناسب درخواست می شود ارائه دهد. برای اطلاعات بیشتر به ادامه مطلب مراجعه کنید:

    توجه: افزودن یک فعالیت برای ارائه دهنده داده شما اختیاری است. برای مثال، ممکن است بخواهید فعالیتی را داشته باشید که تنها زمانی که کاربر روی یک عارضه ضربه می زند، راه اندازی شود.

یک روش برای درخواست های به روز رسانی پیاده سازی کنید

هنگامی که به داده های پیچیده نیاز است، سیستم Wear OS درخواست های به روز رسانی را به ارائه دهنده داده شما ارسال می کند. درخواست ها توسط BroadcastReceiver شما دریافت می شود. برای پاسخ به درخواست‌های به‌روزرسانی، ارائه‌دهنده داده شما باید متد onComplicationUpdate() از کلاس ComplicationProviderService را پیاده‌سازی کند.

سیستم Wear OS زمانی که به داده‌های ارائه‌دهنده شما نیاز دارد onComplicationUpdate() را فراخوانی می‌کند – برای مثال، زمانی که یک عارضه با استفاده از ارائه‌دهنده شما فعال می‌شود یا زمانی که مدت زمان ثابتی می‌گذرد. یک شی ComplicationManager به عنوان پارامتر به onComplicationUpdate ارسال می کند، که برای ارسال داده ها به سیستم استفاده می شود.

توجه: وقتی برنامه ارائه‌دهنده داده شما داده‌ها را ارائه می‌دهد، صفحه ساعت مقادیر خامی را که ارسال می‌کنید دریافت می‌کند تا بتواند اطلاعات را ترسیم کند.

قطعه کد زیر نمونه ای از پیاده سازی متد onComplicationUpdate را نشان می دهد:

کاتلین 

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

جاوا 

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

اعلامیه ها و مجوزهای آشکار

برنامه‌های ارائه‌دهنده داده باید اعلان‌های خاصی را در مانیفست برنامه خود داشته باشند تا توسط سیستم Android به عنوان یک ارائه‌دهنده داده تلقی شوند. این بخش تنظیمات لازم برای برنامه های ارائه دهنده داده را توضیح می دهد.

در مانیفست برنامه‌تان، سرویس را اعلام کنید و یک فیلتر قصد اقدام درخواست به‌روزرسانی اضافه کنید. مانیفست همچنین باید با افزودن مجوز BIND_COMPLICATION_PROVIDER از سرویس محافظت کند تا اطمینان حاصل شود که فقط سیستم Wear OS می‌تواند به خدمات ارائه‌دهنده متصل شود.

همچنین، یک ویژگی android:icon در عنصر service قرار دهید که یک نماد سفید تک رنگ را ارائه می دهد. ما نقشه های برداری برای نمادها را توصیه می کنیم. نماد ارائه دهنده را نشان می دهد و در انتخاب کننده ارائه دهنده نشان داده می شود.

در اینجا یک مثال است:

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    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>
</service>

عناصر متا داده را مشخص کنید

همانطور که در مثال زیر نشان داده شده است، در فایل مانیفست خود، متادیتا را برای تعیین انواع پشتیبانی شده، دوره به روز رسانی و عملکرد پیکربندی قرار دهید:

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" />

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="300" />

وقتی ارائه‌دهنده داده‌های عارضه شما فعال است، UPDATE_PERIOD_SECONDS مشخص می‌کند که هر چند وقت یک‌بار می‌خواهید سیستم برای به‌روزرسانی داده‌ها بررسی کند. اگر اطلاعات نشان داده شده در پیچیدگی نیازی به به روز رسانی در یک برنامه منظم ندارد، مانند زمانی که از به روز رسانی های فشار استفاده می کنید، این مقدار را روی 0 تنظیم کنید.

اگر UPDATE_PERIOD_SECONDS روی 0 تنظیم نکنید، باید از مقدار حداقل 300 (5 دقیقه) استفاده کنید، که حداقل دوره به‌روزرسانی است که سیستم اعمال می‌کند، تا عمر باتری دستگاه حفظ شود. علاوه بر این، به خاطر داشته باشید که زمانی که دستگاه در حالت محیطی قرار دارد یا پوشیده نمی شود، درخواست به روز رسانی کمتر انجام می شود.

برای جزئیات بیشتر در مورد ارسال به‌روزرسانی‌ها، به کلیدهای فهرست شده برای کلاس ComplicationProviderService در مرجع Wear OS API مراجعه کنید.

یک فعالیت پیکربندی اضافه کنید

در صورت لزوم، ارائه‌دهنده می‌تواند یک فعالیت پیکربندی را شامل شود که وقتی کاربر ارائه‌دهنده داده را انتخاب می‌کند به کاربر نشان داده می‌شود. برای گنجاندن فعالیت پیکربندی، یک مورد فراداده را در اعلامیه خدمات ارائه دهنده در مانیفست با کلید زیر وارد کنید:

<meta-data
    android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
    android:value="PROVIDER_CONFIG_ACTION"/>

ارزش می تواند هر عملی باشد.

سپس، اکتیویتی پیکربندی را با یک فیلتر قصد برای آن عمل ایجاد کنید. فعالیت پیکربندی باید در همان بسته ارائه‌دهنده باشد. فعالیت پیکربندی باید RESULT_OK یا RESULT_CANCELED را برگرداند تا به سیستم بگوید که آیا ارائه دهنده باید تنظیم شود.

صفحه های ساعت ایمن مشخص شده توسط ارائه دهنده

ارائه‌دهندگان می‌توانند چهره‌های ساعت خاصی را به‌عنوان «ایمن» برای دریافت اطلاعات خود مشخص کنند. این تنها زمانی استفاده می‌شود که یک ساعت مچی سعی می‌کند از ارائه‌دهنده به‌عنوان پیش‌فرض استفاده کند و ارائه‌دهنده به برنامه چهره ساعت اعتماد دارد.

برای اعلام چهره‌های ساعت به‌عنوان ایمن، ارائه‌دهنده ابرداده را با کلید android.support.wearable.complications.SAFE_WATCH_FACES اضافه می‌کند. مقدار فراداده یک لیست جدا شده با کاما از نام مؤلفه‌های WatchFaceService است که گویی ComponentName.flattenToString() فراخوانی می‌شود، یا نام‌های بسته برنامه، در این صورت هر صفحه ساعت در یک برنامه مشخص امن در نظر گرفته می‌شود. فضای خالی در لیست مقادیر نادیده گرفته می شود. به عنوان مثال:

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

ارائه تصاویر ایمن سوختگی

در صفحه نمایش هایی که در معرض سوختن هستند، باید از بلوک های رنگی جامد در حالت محیطی اجتناب شود. اگر نمادها یا تصاویر شما دارای بلوک های رنگی ثابت هستند، نسخه ایمن را نیز ارائه دهید.

وقتی نمادی را با استفاده از ComplicationData.Builder#setIcon ارائه می‌کنید، نسخه ایمن را با استفاده از ComplicationData.Builder#setBurnInProtectionIcon اضافه کنید.

هنگامی که تصویری را با استفاده از ComplicationData.Builder#setSmallImage ارائه می‌کنید، نسخه ایمن را با استفاده از ComplicationData.Builder#setBurnInProtectionSmallImage اضافه کنید.

از به روز رسانی های فشار استفاده کنید

به عنوان جایگزینی برای تعیین فاصله ثابت و غیرصفر به‌روزرسانی برای یک عارضه در مانیفست برنامه‌تان، می‌توانید از نمونه‌ای از ComplicationDataSourceUpdateRequester برای درخواست به‌روزرسانی‌ها به صورت پویا استفاده کنید. برای درخواست به‌روزرسانی برای محتوای قابل مشاهده توسط کاربر، با requestUpdate() تماس بگیرید.

احتیاط: برای حفظ عمر باتری دستگاه، به طور میانگین هر 5 دقیقه یکبار درخواست requestUpdate() از نمونه ComplicationDataSourceUpdateRequester فراخوانی نکنید.

مقادیر پویا را ارائه دهید

با شروع در Wear OS 4، برخی از پیچیدگی‌ها می‌توانند مقادیری را نشان دهند که بر اساس مقادیری که مستقیماً در پلتفرم در دسترس هستند، بیشتر به‌روزرسانی می‌شوند. برای ارائه این قابلیت در پیچیدگی های خود، از فیلدهای ComplicationData استفاده کنید که مقادیر پویا را می پذیرند. پلتفرم این مقادیر را مرتباً ارزیابی و به روز می کند، بدون اینکه نیازی به اجرای ارائه دهنده عوارض داشته باشد.

فیلدهای مثال شامل فیلد مقدار پویا GoalProgressComplicationData و DynamicComplicationText است که می‌تواند در هر فیلد ComplicationText استفاده شود. این مقادیر پویا بر اساس کتابخانه androidx.wear.protolayout.expression هستند.

در شرایط خاص، پلت فرم نمی تواند مقادیر پویا را ارزیابی کند:

  • مقدار پویا گاهی اوقات در دسترس نیست: این اتفاق می افتد، برای مثال، زمانی که دستگاه خارج از مچ است. در این شرایط، پلتفرم از مقدار فیلد بازگشتی باطل ارزش پویا در قسمت جای‌بان NoDataComplicationData استفاده می‌کند.
  • مقدار پویا هرگز در دسترس نیست: این اتفاق در دستگاهی رخ می‌دهد که در نسخه قدیمی‌تر Wear OS 4 اجرا می‌شود. در این شرایط، پلتفرم از یک فیلد بازگشتی همراه، مانند getFallbackValue () استفاده می‌کند.

مقادیر وابسته به زمان را ارائه دهید

برخی از عوارض باید مقداری را نشان دهند که به زمان فعلی مربوط می شود. به عنوان مثال می توان به تاریخ فعلی، زمان تا جلسه بعدی یا زمان منطقه زمانی دیگر اشاره کرد.

یک عارضه را هر ثانیه یا دقیقه به روز نکنید تا آن مقادیر را به روز نگه دارید. در عوض، با استفاده از متن وابسته به زمان، مقادیر را نسبت به تاریخ یا زمان فعلی مشخص کنید. برای ایجاد این مقادیر وابسته به زمان می توانید از سازنده ها در کلاس ComplicationText استفاده کنید.

نرخ به روز رسانی عوارض

ممکن است بخواهید عوارض را با سرعتی سریع به روز کنید. با این حال، این ممکن است بر عمر باتری دستگاه تأثیر بگذارد. می‌توانید انتخاب کنید که از یک API درخواست عوارض ممتاز استفاده کنید که به عوارض خاص اجازه می‌دهد بیشتر به‌روزرسانی شوند. با این حال، استفاده از این API باید توسط سازنده ساعت مجاز باشد. هر سازنده ساعت تصمیم می گیرد که کدام عوارض می توانند با سرعتی سریعتر از حد معمول به روز شوند.