کانال ها در صفحه اصلی

صفحه اصلی Android TV یا به سادگی صفحه اصلی ، یک رابط کاربری ارائه می دهد که محتوای توصیه شده را به عنوان جدولی از کانال ها و برنامه ها نمایش می دهد. هر ردیف یک کانال است. یک کانال حاوی کارت هایی برای هر برنامه موجود در آن کانال است:

این سند نحوه افزودن کانال ها و برنامه ها را به صفحه اصلی، به روز رسانی محتوا، مدیریت اقدامات کاربر و ارائه بهترین تجربه برای کاربران خود نشان می دهد. (اگر می‌خواهید عمیق‌تر در API کاوش کنید، کد لبه صفحه اصلی را امتحان کنید و جلسه I/O 2017 Android TV را تماشا کنید.)

توجه: کانال‌های توصیه‌ها فقط در Android 8.0 (سطح API 26) و جدیدتر در دسترس هستند. باید از آنها برای ارائه توصیه‌هایی برای برنامه‌های اجرا شده در Android نسخه 8.0 (سطح API 26) و جدیدتر استفاده کنید. برای ارائه توصیه‌هایی برای برنامه‌هایی که در نسخه‌های قبلی Android اجرا می‌شوند، برنامه شما باید به جای آن از ردیف توصیه‌ها استفاده کند.

رابط کاربری صفحه اصلی

برنامه ها می توانند کانال های جدید ایجاد کنند، برنامه ها را در یک کانال اضافه، حذف و به روز کنند و ترتیب برنامه ها را در یک کانال کنترل کنند. برای مثال، یک برنامه می‌تواند کانالی به نام «چه خبر» ایجاد کند و کارت‌هایی را برای برنامه‌های تازه در دسترس نشان دهد.

برنامه ها نمی توانند ترتیب ظاهر شدن کانال ها در صفحه اصلی را کنترل کنند. وقتی برنامه شما یک کانال جدید ایجاد می کند، صفحه اصلی آن را به پایین لیست کانال اضافه می کند. کاربر می‌تواند کانال‌ها را دوباره مرتب کند، پنهان کند و نشان دهد.

کانال تماشای بعدی

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

توجه: در صفحه اصلی، کانال تماشای بعدی دارای برچسب Play Next است.

کانال های برنامه

کانال هایی که برنامه شما ایجاد می کند همه از این چرخه زندگی پیروی می کنند:

1. کاربر کانالی را در برنامه شما پیدا می کند و درخواست می کند آن را به صفحه اصلی اضافه کند.
2. برنامه کانال را ایجاد می کند و آن را به TvProvider اضافه می کند (در این مرحله کانال قابل مشاهده نیست).
3. برنامه از سیستم می خواهد که کانال را نمایش دهد.
4. سیستم از کاربر می خواهد که کانال جدید را تایید کند.
5. کانال جدید در آخرین ردیف صفحه اصلی ظاهر می شود.

کانال پیش فرض

برنامه شما می تواند هر تعداد کانالی را به کاربر ارائه دهد تا به صفحه اصلی اضافه کند. کاربر معمولاً باید هر کانال را قبل از ظاهر شدن در صفحه اصلی انتخاب و تأیید کند. هر برنامه امکان ایجاد یک کانال پیش فرض را دارد. کانال پیش فرض ویژه است زیرا به طور خودکار در صفحه اصلی ظاهر می شود. کاربر مجبور نیست صریحاً آن را درخواست کند.

پیش نیازها

صفحه اصلی Android TV از API های TvProvider Android برای مدیریت کانال ها و برنامه هایی که برنامه شما ایجاد می کند استفاده می کند. برای دسترسی به داده های ارائه دهنده، مجوز زیر را به مانیفست برنامه خود اضافه کنید:

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

توجه: مجوز READ_EPG_DATA در Android M (API 23) منسوخ شده است و دیگر مورد نیاز نیست.

کتابخانه پشتیبانی 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

جاوا

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 را برمی‌گرداند.

برای ایجاد کانال، مراحل زیر را دنبال کنید:

1. یک کانال ساز ایجاد کنید و ویژگی های آن را تنظیم کنید. توجه داشته باشید که نوع کانال باید 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)

   جاوا

   Channel.Builder builder = new Channel.Builder();
   // Every channel you create must have the type TYPE_PREVIEW
   builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
           .setDisplayName("Channel Name")
           .setAppLinkIntentUri(uri);

2. کانال را در ارائه دهنده قرار دهید:

   کاتلین

   var channelUri = context.contentResolver.insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())

   جاوا

   Uri channelUri = context.getContentResolver().insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());

3. شما باید شناسه کانال را ذخیره کنید تا بعداً برنامه ها را به کانال اضافه کنید. شناسه کانال را از URI برگشتی استخراج کنید:

   کاتلین

   var channelId = ContentUris.parseId(channelUri)

   جاوا

   long channelId = ContentUris.parseId(channelUri);

4. شما باید یک لوگو برای کانال خود اضافه کنید. از Uri یا Bitmap استفاده کنید. نماد لوگو باید 80dp x 80dp باشد و باید غیرشفاف باشد. زیر یک ماسک دایره ای نمایش داده می شود:

   

   کاتلین

   // Choose one or the other
   storeChannelLogo(context: Context, channelId: Long, logoUri: Uri) // also works if logoUri is a URL
   storeChannelLogo(context: Context, channelId: Long, logo: Bitmap)

   جاوا

   // Choose one or the other
   storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
   storeChannelLogo(Context context, long channelId, Bitmap logo);

5. ایجاد کانال پیش‌فرض (اختیاری): وقتی برنامه شما اولین کانال خود را ایجاد می‌کند، می‌توانید آن را به کانال پیش‌فرض تبدیل کنید تا بلافاصله بدون هیچ اقدام کاربر در صفحه اصلی ظاهر شود. هر کانال دیگری که ایجاد می کنید تا زمانی که کاربر به صراحت آنها را انتخاب نکند قابل مشاهده نیست.

   کاتلین

   TvContractCompat.requestChannelBrowsable(context, channelId)

   جاوا

   TvContractCompat.requestChannelBrowsable(context, channelId);

6. کانال پیش‌فرض خود را قبل از باز شدن برنامه نشان دهید. می‌توانید این رفتار را با افزودن یک 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>

   هنگام بارگذاری جانبی برنامه خود در حین توسعه، می توانید این مرحله را با راه اندازی intent از طریق 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
)

جاوا

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

برای به روز رسانی لوگوی کانال، از storeChannelLogo() استفاده کنید.

حذف یک کانال

کاتلین

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

جاوا

context.getContentResolver().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)

جاوا

PreviewProgram.Builder builder = new 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())

جاوا

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

شناسه برنامه را برای مراجعه بعدی بازیابی کنید:

کاتلین

val programId = ContentUris.parseId(programUri)

جاوا

long programId = ContentUris.parseId(programUri);

افزودن برنامه به کانال Watch Next

برای درج برنامه‌ها در کانال تماشای بعدی، به افزودن برنامه‌ها به کانال تماشای بعدی مراجعه کنید.

به روز رسانی یک برنامه

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

از یک PreviewProgram.Builder برای تنظیم ویژگی هایی که باید تغییر دهید استفاده کنید، سپس getContentResolver().update برای به روز رسانی برنامه فراخوانی کنید. شناسه برنامه ای را که هنگام اضافه شدن برنامه ذخیره کرده اید مشخص کنید:

کاتلین

context.contentResolver.update(
        TvContractCompat.buildPreviewProgramUri(programId),
                builder.build().toContentValues(), null, null
)

جاوا

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

حذف یک برنامه

کاتلین

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

جاوا

context.getContentResolver().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
}

جاوا

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

سیستم یک گفتگو را نمایش می دهد که از کاربر می خواهد کانال را تأیید کند. نتیجه درخواست را در روش onActivityResult فعالیت خود مدیریت کنید ( Activity.RESULT_CANCELED یا Activity.RESULT_OK ).

رویدادهای صفحه اصلی Android TV

هنگامی که کاربر با برنامه ها/کانال های منتشر شده توسط برنامه تعامل برقرار می کند، صفحه اصلی اهداف را به برنامه ارسال می کند:

• هنگامی که کاربر نشان‌واره کانال را انتخاب می‌کند، صفحه اصلی Uri ذخیره شده در ویژگی APP_LINK_INTENT_URI یک کانال را به برنامه ارسال می‌کند. برنامه فقط باید رابط کاربری اصلی خود یا نمای مربوط به کانال انتخاب شده را راه اندازی کند.
• هنگامی که کاربر برنامه ای را انتخاب می کند، صفحه اصلی Uri ذخیره شده در ویژگی INTENT_URI یک برنامه را به برنامه می فرستد. برنامه باید محتوای انتخاب شده را پخش کند.
• کاربر می تواند نشان دهد که دیگر به برنامه ای علاقه ای ندارد و می خواهد آن را از رابط کاربری صفحه اصلی حذف کند. سیستم برنامه را از رابط کاربری حذف می‌کند و برای برنامه‌ای که برنامه را در اختیار دارد یک intent (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 and cursor.moveToNext()) {
                             val channel = Channel.fromCursor(cursor)
                             if (channel.isBrowsable()) {
                                 //update channel's programs
                             }
                         }
            })

  جاوا

  try (Cursor cursor = context.getContentResolver()
        .query(
            TvContractCompat.buildChannelUri(channelId),
            null,
            null,
            null,
            null)) {
                if (cursor != null && cursor.moveToNext()) {
                    Channel channel = Channel.fromCursor(cursor);
                    if (channel.isBrowsable()) {
                        //update channel's programs
                    }
                }
            }

• از Uris منحصر به فرد برای همه تصاویر (آرم ها، نمادها، تصاویر محتوا) استفاده کنید. هنگام به روز رسانی یک تصویر، حتما از یک Uri متفاوت استفاده کنید. تمامی تصاویر ذخیره شده اند. اگر هنگام تغییر تصویر Uri را تغییر ندهید، تصویر قدیمی همچنان ظاهر می شود.

• به یاد داشته باشید که بندهای WHERE مجاز نیستند و تماس با ارائه دهندگان با بندهای WHERE یک استثنا امنیتی ایجاد می کند.

صفات

این بخش ویژگی های کانال و برنامه را به طور جداگانه شرح می دهد.

ویژگی های کانال

شما باید این ویژگی ها را برای هر کانال مشخص کنید:

صفت	یادداشت ها
تایپ کنید	روی TYPE_PREVIEW تنظیم کنید.
DISPLAY_NAME	روی نام کانال تنظیم کنید.
APP_LINK_INTENT_URI	هنگامی که کاربر لوگوی کانال را انتخاب می کند، سیستم قصدی برای شروع فعالیتی ارسال می کند که محتوای مرتبط با کانال را ارائه می دهد. این ویژگی را روی Uri استفاده شده در فیلتر intent برای آن فعالیت تنظیم کنید.

علاوه بر این، یک کانال همچنین دارای شش فیلد برای استفاده داخلی برنامه است. از این فیلدها می توان برای ذخیره کلیدها یا مقادیر دیگری استفاده کرد که می تواند به برنامه کمک کند کانال را با ساختار داده داخلی خود ترسیم کند:

• INTERNAL_PROVIDER_ID
• INTERNAL_PROVIDER_DATA
• INTERNAL_PROVIDER_FLAG1
• INTERNAL_PROVIDER_FLAG2
• INTERNAL_PROVIDER_FLAG3
• INTERNAL_PROVIDER_FLAG4

ویژگی های برنامه

برای ویژگی های هر نوع برنامه، صفحات جداگانه را ببینید:

• ویژگی های برنامه ویدیویی
• ویژگی های برنامه صوتی
• ویژگی های برنامه بازی
• ویژگی های برنامه بعدی را تماشا کنید

کد نمونه

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