صفحه اصلی Android TV میانای کاربری ارائه میدهد که محتوای توصیهشده را بهصورت جدولی از کانالها و برنامهها نمایش میدهد. هر ردیف یک کانال است. هر کانال حاوی کارتهایی برای هر برنامه موجود در آن کانال است:
این سند نحوه افزودن کانالها و برنامهها به صفحه اصلی، بهروزرسانی محتوا، مدیریت کنشهای کاربر، و ارائه بهترین تجربه برای کاربران را نشان میدهد. (اگر میخواهید عمیقتر در API کاوش کنید، آزمایشگاه کد صفحه اصلی را امتحان کنید و جلسه Android TV در I/O 2017 را تماشا کنید)
میانای کاربر صفحه اصلی
برنامهها میتوانند کانالهای جدید ایجاد کنند، برنامهها را در کانال اضافه، حذف، و بهروزرسانی کنند، و ترتیب برنامهها را در کانال کنترل کنند. برای مثال، برنامهای میتواند کانالی بهنام «تازهها» ایجاد کند و کارتهایی برای برنامههای جدیداً دردسترس نشان دهد.
برنامهها نمیتوانند ترتیب نمایش کانالها را در صفحه اصلی کنترل کنند. وقتی برنامهتان کانال جدیدی ایجاد میکند، صفحه اصلی آن را به پایین فهرست کانال اضافه میکند. کاربر میتواند ترتیب کانالها را تغییر دهد، آنها را پنهان کند، و نمایش دهد.
کانال «تماشای بعدی»
کانال «صف پخش» ردیف دومی است که در صفحه اصلی، بعداز ردیف برنامهها، نشان داده میشود. سیستم این کانال را ایجاد و نگهداری میکند. برنامهتان میتواند برنامههایی را به کانال «بعدی برای تماشا» اضافه کند. برای اطلاعات بیشتر، به افزودن برنامهها به کانال «بعدی برای تماشا» مراجعه کنید.
کانالهای برنامه
کانالهایی که برنامهتان ایجاد میکند همگی از این چرخه حیات پیروی میکنند:
- کاربر کانالی را در برنامه شما پیدا میکند و درخواست میکند آن را به صفحه اصلی اضافه کند.
- برنامه کانال را ایجاد میکند و آن را به
TvProviderاضافه میکند (در این مرحله کانال قابلمشاهده نیست). - برنامه از سیستم میخواهد کانال را نمایش دهد.
- سیستم از کاربر میخواهد کانال جدید را تأیید کند.
- کانال جدید در آخرین ردیف صفحه اصلی نشان داده میشود.
کانال پیشفرض
برنامه شما میتواند هر تعداد کانال را برای افزودن کاربر به صفحه اصلی ارائه دهد. کاربر معمولاً باید هر کانال را قبلاز اینکه در صفحه اصلی ظاهر شود انتخاب و تأیید کند. هر برنامه گزینه ایجاد یک کانال پیشفرض را دارد. کانال پیشفرض خاص است زیرا بهطور خودکار در صفحه اصلی ظاهر میشود؛ کاربر مجبور نیست بهطور صریح آن را درخواست کند.
پیشنیازها
صفحه اصلی Android TV از میاناهای برنامهسازی کاربردی TvProvider Android برای مدیریت
کانالها و برنامههایی که برنامه شما ایجاد میکند استفاده میکند. برای دسترسی به دادههای ارائهدهنده،
اجازه زیر را به مانیفست برنامهتان اضافه کنید:
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
کتابخانه پشتیبانی TvProvider استفاده از ارائهدهنده را آسانتر میکند. آن را به
وابستگیها در فایل build.gradle اضافه کنید:
شیک
implementation 'androidx.tvprovider:tvprovider:1.0.0'
کاتلین
implementation("androidx.tvprovider:tvprovider:1.0.0")
برای کار با کانالها و برنامهها، حتماً این واردات کتابخانه پشتیبانی را در برنامه خود بگنجانید:
import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram
کانالها
اولین کانالی که برنامهتان ایجاد میکند کانال پیشفرض آن میشود. کانال پیشفرض بهطور خودکار در صفحه اصلی نشان داده میشود. همه کانالهای دیگری که ایجاد میکنید باید توسط کاربر انتخاب و پذیرفته شوند تا بتوانند در صفحه اصلی نشان داده شوند.
ایجاد کردن کانال
برنامه شما باید از سیستم بخواهد کانالهای جدیداً اضافهشده را فقط زمانی نشان دهد که
در پیشزمینه اجرا میشود. این کار مانع از نمایش کادر گفتگویی میشود که در آن برنامهتان درخواست تأیید برای افزودن کانال شما را دارد، درحالیکه کاربر درحال اجرای برنامه دیگری است. اگر سعی کنید کانالی را درحین اجرا در پسزمینه اضافه کنید، روش onActivityResult() فعالیت کد وضعیت RESULT_CANCELED را برمیگرداند.
برای ایجاد کانال، این مراحل را دنبال کنید:
سازنده کانال ایجاد کنید و مشخصههای آن را تنظیم کنید. توجه داشته باشید که نوع کانال باید
TYPE_PREVIEWباشد. مشخصههای بیشتری را درصورت نیاز اضافه کنید.val builder = Channel.Builder() // Every channel you create must have the type `TYPE_PREVIEW`. builder.setType(TvContractCompat.Channels.TYPE_PREVIEW) .setDisplayName("Channel Name") .setAppLinkIntentUri(uri)
کانال را در ارائهدهنده وارد کنید:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
برای اینکه بتوانید بعداً به کانال برنامه اضافه کنید، باید شناسه کانال را ذخیره کنید. شناسه کانال را از URI برگرداندهشده استخراج کنید:
var channelId = ContentUris.parseId(channelUri)
باید برای کانالتان نشانواره اضافه کنید. از
UriیاBitmapاستفاده کنید. نماد نشانواره باید ۸۰ دیپی در ۸۰ دیپی باشد و باید مات باشد. این نماد زیر ماسک دایرهای نمایش داده میشود:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
ایجاد کانال پیشفرض (اختیاری): وقتی برنامهتان اولین کانال خود را ایجاد میکند، میتوانید آن را به کانال پیشفرض تبدیل کنید تا بلافاصله بدون هیچ اقدامی ازسوی کاربر در صفحه اصلی ظاهر شود. هر کانال دیگری که ایجاد میکنید تا زمانی که کاربر صریحاً آنها را انتخاب نکند، قابلمشاهده نیست.
TvContractCompat.requestChannelBrowsable(context, channelId)
کاری کنید که کانال پیشفرضتان قبلاز باز شدن برنامهتان نشان داده شود. میتوانید با افزودن
BroadcastReceiverکه به کنشandroid.media.tv.action.INITIALIZE_PROGRAMSگوش میدهد، این رفتار را ایجاد کنید. صفحه اصلی این کنش را پساز نصب برنامه ارسال میکند:<receiver android:name=".RunOnInstallReceiver" android:exported="true"> <intent-filter> <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </receiver>هنگام بارگذاری جانبی برنامهتان درطول توسعه، میتوانید این مرحله را با راهاندازی هدف ازطریق adb آزمایش کنید، که در آن your.package.name/.YourReceiverName
BroadcastReceiverبرنامهتان است:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameدر موارد نادر، ممکن است برنامهتان همزمان با شروع برنامه توسط کاربر، رویداد ثبتشده را دریافت کند. مطمئن شوید کدتان بیشاز یکبار برای افزودن کانال پیشفرض تلاش نکند.
بهروزرسانی کانال
بهروزرسانی کانالها بسیار شبیه به ایجاد آنها است.
از Channel.Builder دیگری برای تنظیم مشخصههایی که باید تغییر کنند استفاده کنید.
از ContentResolver برای بهروزرسانی کانال استفاده کنید. از شناسه کانالی که هنگام اضافه شدن اولیه کانال ذخیره کردهاید استفاده کنید:
context.contentResolver.update( TvContractCompat.buildChannelUri(channelId), builder.build().toContentValues(), null, null )
برای بهروزرسانی نشانواره کانال، از storeChannelLogo() استفاده کنید.
حذف کردن کانال
context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)
برنامهها
برنامهها کارتهای محتوای تکی هستند که در کانال نمایش داده میشوند. میتوانید برنامهها را هم در کانالهای سفارشی برنامهتان و هم در کانال «تماشای بعدی» که توسط سیستم مدیریت میشود منتشر کنید.
افزودن برنامهها به کانال برنامه
PreviewProgram.Builder ایجاد کنید و مشخصههای آن را تنظیم کنید:
val builder = PreviewProgram.Builder() builder.setChannelId(channelId) .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP) .setTitle("Title") .setDescription("Program description") .setPosterArtUri(uri) .setIntentUri(uri) .setInternalProviderId(appProgramId)
بسته به نوع برنامه، مشخصههای بیشتری اضافه کنید. (برای دیدن مشخصههای موجود برای هر نوع برنامه، به جدولهای زیر مراجعه کنید.)
برنامه را در ارائهدهنده درج کنید:
var programUri = context.contentResolver.insert( TvContractCompat.PreviewPrograms.CONTENT_URI, builder.build().toContentValues() )
شناسه برنامه را برای ارجاع در آینده بازیابی کنید:
val programId = ContentUris.parseId(programUri)
افزودن برنامهها به کانال «تماشای بعدی»
برای درج برنامهها در کانال «بعدی برای تماشا»، به افزودن برنامهها به کانال «بعدی برای تماشا» مراجعه کنید.
درحال بهروزرسانی برنامه
میتوانید اطلاعات برنامه را تغییر دهید. برای مثال، ممکن است بخواهید قیمت اجاره فیلمی را بهروز کنید، یا نوار پیشرفتی را بهروز کنید که نشان میدهد کاربر چه مقدار از برنامه را تماشا کرده است.
از PreviewProgram.Builder برای تنظیم مشخصههایی که باید تغییر دهید استفاده کنید، سپس
getContentResolver().update را برای بهروزرسانی برنامه فراخوانی کنید. شناسه برنامهای را که هنگام افزودن اولیه برنامه ذخیره کردهاید مشخص کنید:
context.contentResolver.update( TvContractCompat.buildPreviewProgramUri(programId), builder.build().toContentValues(), null, null )
درحال حذف برنامه
context.contentResolver .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)
رسیدگی به کنشهای کاربر
برنامه شما میتواند با ارائه میانای کاربر برای نمایش و افزودن کانالها، به کاربران کمک کند محتوا را کاوش کنند. برنامه شما باید تعامل با کانالهایتان را پساز ظاهر شدن در صفحه اصلی نیز مدیریت کند.
کاوش و افزودن کانالها
برنامه شما میتواند عنصر میانای کاربری ارائه دهد که به کاربر اجازه میدهد کانالهای آن را انتخاب و اضافه کند (برای مثال، دکمهای که درخواست میکند کانال اضافه شود).
پساز اینکه کاربر کانال خاصی را درخواست کرد، این کد را اجرا کنید تا اجازه کاربر را برای افزودن آن به میانای کاربر صفحه اصلی دریافت کنید:
val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
// handle error
}
سیستم کادر گفتگویی را نمایش میدهد که از کاربر میخواهد کانال را تأیید کند. نتیجه درخواست را در روش onActivityResult فعالیتتان (Activity.RESULT_CANCELED یا Activity.RESULT_OK) مدیریت کنید.
رویدادهای صفحه اصلی Android TV
وقتی کاربر با برنامهها و کانالهای منتشرشده توسط برنامه تعامل برقرار میکند، صفحه اصلی هدفهایی را به برنامه ارسال میکند:
- وقتی کاربر نشانواره کانال را انتخاب میکند، صفحه اصلی
Uriذخیرهشده در مشخصه APP_LINK_INTENT_URI کانال را به برنامه ارسال میکند. برنامه باید فقط میانای کاربر اصلی یا نمای مربوط به کانال انتخابشده را راهاندازی کند. - وقتی کاربر برنامهای را انتخاب میکند، صفحه اصلی
Uriذخیرهشده در مشخصه INTENT_URI برنامه را به برنامه ارسال میکند. برنامه باید محتوای انتخابشده را پخش کند. - کاربر میتواند نشان دهد که دیگر به برنامهای علاقه ندارد و میخواهد آن برنامه از میانای کاربر صفحه اصلی برداشته شود. سیستم برنامه را از میانای کاربر برمیدارد و قصدی (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED یا android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) با شناسه برنامه به برنامهای که مالک برنامه است ارسال میکند. برنامه باید برنامه را از ارائهدهنده بردارد و نباید آن را دوباره درج کند.
حتماً برای همه Uris که صفحه اصلی برای تعاملات کاربر ارسال میکند، فیلترهای قصد ایجاد کنید؛ برای مثال:
<receiver
android:name=".WatchNextProgramRemoved"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
</intent-filter>
</receiver>
سایر ملاحظات
- بسیاری از برنامههای تلویزیون از کاربران میخواهند به سیستم وارد شوند. در این مورد،
BroadcastReceiverکه بهandroid.media.tv.action.INITIALIZE_PROGRAMSگوش میدهد باید محتوای کانال را برای کاربران تأییدنشده پیشنهاد دهد. برای مثال، برنامهتان میتواند در ابتدا بهترین محتوا یا محتوای پرطرفدار فعلی را نشان دهد. پساز اینکه کاربر به سیستم وارد شد، میتواند محتوای شخصیسازیشده را نشان دهد. این فرصت خوبی برای برنامهها است تا قبلاز ورود کاربران به سیستم، فروش ویژه داشته باشند. - وقتی برنامهتان در پیشنما نیست و باید کانال یا برنامهای را بهروز کنید، از
JobSchedulerبرای زمانبندی کار استفاده کنید (JobSchedulerوJobServiceرا ببینید). - اگر برنامه شما رفتار نادرستی داشته باشد (برای مثال، بهطور مداوم دادههای هرزنامه به ارائهدهنده ارسال کند)، سیستم میتواند اجازههای ارائهدهنده برنامه شما را لغو کند. مطمئن شوید که کد دسترسی به ارائهدهنده را با بندهای try-catch برای رسیدگی به استثناهای امنیتی بپوشانید.
- قبلاز بهروزرسانی برنامهها و کانالها، دادههایی را که باید بهروزرسانی و تطبیق دهید از ارائهدهنده درخواست کنید. برای مثال، نیازی نیست برنامهای را که کاربر میخواهد از میانای کاربر برداشته شود بهروز کنید. از کار پسزمینهای استفاده کنید که دادههایتان را پساز جستجوی دادههای موجود و سپس درخواست تأیید برای کانالهایتان، در ارائهدهنده درج یا بهروزرسانی کند. میتوانید این کار را هنگام شروع برنامه و هر زمان که برنامه نیاز به بهروزرسانی دادههای خود دارد، اجرا کنید.
context.contentResolver .query( TvContractCompat.buildChannelUri(channelId), null, null, null, null ).use({ cursor -> if (cursor != null && cursor.moveToNext()) { val channel = Channel.fromCursor(cursor) if (channel.isBrowsable()) { // update channel's programs. } } })
- از شناسه منبع یکسان یکتا برای همه تصاویر (نشانوارهها، نمادها، تصاویر محتوا) استفاده کنید. حتماً هنگام بهروزرسانی تصویر از Uri دیگری استفاده کنید. همه تصاویر در حافظه نهان ذخیره شدهاند. اگر هنگام تغییر تصویر، Uri را تغییر ندهید، تصویر قدیمی همچنان نمایش داده خواهد شد.
- بهخاطر داشته باشید که عبارتهای WHERE مجاز نیستند و فراخوانی ارائهدهندگان با عبارتهای WHERE استثنای امنیتی ایجاد میکند.
مشخصهها
این بخش مشخصههای کانال و برنامه را بهطور جداگانه شرح میدهد.
مشخصههای کانال
باید این مشخصهها را برای هر کانال تعیین کنید:
| مشخصه | یادداشتها |
|---|---|
| نوع | روی TYPE_PREVIEW تنظیم شده است. |
| DISPLAY_NAME | به نام کانال تنظیم شده است. |
| APP_LINK_INTENT_URI | وقتی کاربر نشانواره کانال را انتخاب میکند، سیستم قصدی را برای شروع فعالیتی ارسال میکند که محتوای مربوط به کانال را ارائه میدهد. این مشخصه را روی Uri استفادهشده در فیلتر هدف برای آن فعالیت تنظیم کنید. |
علاوهبراین، کانال شش فیلد هم دارد که برای استفاده داخلی برنامه رزرو شده است. از این فیلدها میتوان برای ذخیره کلیدها یا مقادیر دیگری استفاده کرد که میتوانند به برنامه کمک کنند کانال را به ساختار دادههای داخلی خود نگاشت کند:
- INTERNAL_PROVIDER_ID
- INTERNAL_PROVIDER_DATA
- INTERNAL_PROVIDER_FLAG1
- INTERNAL_PROVIDER_FLAG2
- INTERNAL_PROVIDER_FLAG3
- INTERNAL_PROVIDER_FLAG4
مشخصههای برنامه
برای مشخصههای هر نوع برنامه، به صفحههای جداگانه مراجعه کنید:
- مشخصههای برنامه ویدیویی
- مشخصههای برنامه صوتی
- مشخصههای برنامه بازی
- مشخصههای برنامه «بعدی برای تماشا»
کد نمونه
برای کسب اطلاعات بیشتر درباره ساخت برنامههایی که با صفحه اصلی تعامل دارند و افزودن کانالها و برنامهها به صفحه اصلی Android TV، به آزمایشگاه کد صفحه اصلی ما مراجعه کنید.