Các kênh trên màn hình chính

Màn hình chính của Android TV cung cấp một giao diện người dùng hiển thị nội dung đề xuất dưới dạng bảng kênh và chương trình. Mỗi hàng là một kênh. Một kênh chứa các thẻ cho mọi chương trình có trên kênh đó:

Màn hình chính của Android TV
Màn hình chính của Android TV

Tài liệu này minh hoạ cách thêm kênh và chương trình vào màn hình chính, cập nhật nội dung, xử lý hành động của người dùng và mang lại trải nghiệm tốt nhất cho người dùng. (Nếu bạn muốn tìm hiểu sâu hơn về API, hãy thử lớp học lập trình về màn hình chính và xem phiên Android TV I/O 2017)

Giao diện người dùng của màn hình chính

Ứng dụng có thể tạo kênh mới, thêm, xoá và cập nhật chương trình trong kênh, đồng thời kiểm soát thứ tự của các chương trình trong kênh. Ví dụ: một ứng dụng có thể tạo một kênh có tên là "Tính năng mới" và hiển thị thẻ cho các chương trình mới có sẵn.

Ứng dụng không thể kiểm soát thứ tự xuất hiện của các kênh trên màn hình chính. Khi ứng dụng của bạn tạo một kênh mới, màn hình chính sẽ thêm kênh đó vào cuối danh sách kênh. Người dùng có thể sắp xếp lại, ẩn và hiện kênh.

Kênh danh sách video phát tiếp theo

Kênh danh sách video phát tiếp theo là hàng thứ hai xuất hiện trên màn hình chính, sau hàng ứng dụng. Hệ thống tạo ra và duy trì kênh này. Ứng dụng của bạn có thể thêm chương trình vào kênh danh sách video phát tiếp theo. Để biết thêm thông tin, hãy xem phần Thêm chương trình vào kênh Watch Next.

Kênh ứng dụng

Các kênh mà ứng dụng của bạn tạo đều tuân theo vòng đời này:

  1. Người dùng khám phá một kênh trong ứng dụng của bạn và yêu cầu thêm kênh đó vào màn hình chính.
  2. Ứng dụng tạo kênh và thêm kênh vào TvProvider (tại thời điểm này, kênh không hiển thị).
  3. Ứng dụng yêu cầu hệ thống hiển thị kênh.
  4. Hệ thống yêu cầu người dùng phê duyệt kênh mới.
  5. Kênh mới xuất hiện ở hàng cuối cùng của màn hình chính.

Kênh mặc định

Ứng dụng của bạn có thể cung cấp số lượng kênh bất kỳ để người dùng thêm vào màn hình chính. Người dùng thường phải chọn và phê duyệt từng kênh trước khi kênh đó xuất hiện trên màn hình chính. Mỗi ứng dụng đều có thể tạo một kênh mặc định. Kênh mặc định là kênh đặc biệt vì kênh này tự động xuất hiện trên màn hình chính; người dùng không cần phải yêu cầu rõ ràng.

Điều kiện tiên quyết

Màn hình chính của Android TV sử dụng API TvProvider của Android để quản lý các kênh và chương trình mà ứng dụng của bạn tạo. Để truy cập vào dữ liệu của nhà cung cấp, hãy thêm quyền sau vào tệp kê khai của ứng dụng:

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

Thư viện hỗ trợ TvProvider giúp bạn dễ dàng sử dụng nhà cung cấp hơn. Thêm phần phụ thuộc này vào các phần phụ thuộc trong tệp build.gradle:

Groovy

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

implementation("androidx.tvprovider:tvprovider:1.0.0")

Để làm việc với các kênh và chương trình, hãy nhớ thêm các lệnh nhập thư viện hỗ trợ này vào chương trình của bạn:

Kotlin

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

Java

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;

Kênh

Kênh đầu tiên mà ứng dụng của bạn tạo sẽ trở thành kênh mặc định. Kênh mặc định sẽ tự động xuất hiện trên màn hình chính. Tất cả các kênh khác mà bạn tạo phải được người dùng chọn và chấp nhận thì mới có thể xuất hiện trên màn hình chính.

Tạo kênh

Ứng dụng của bạn chỉ nên yêu cầu hệ thống hiển thị các kênh mới thêm khi ứng dụng đang chạy ở nền trước. Điều này giúp ứng dụng của bạn không hiển thị hộp thoại yêu cầu phê duyệt để thêm kênh trong khi người dùng đang chạy một ứng dụng khác. Nếu bạn cố gắng thêm kênh trong khi chạy ở chế độ nền, thì phương thức onActivityResult() của hoạt động sẽ trả về mã trạng thái RESULT_CANCELED.

Để tạo kênh, hãy làm theo các bước sau:

  1. Tạo trình tạo kênh và đặt các thuộc tính của trình tạo kênh. Xin lưu ý rằng loại kênh phải là TYPE_PREVIEW. Thêm các thuộc tính khác nếu cần.

    Kotlin

    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)

    Java

    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. Chèn kênh vào nhà cung cấp:

    Kotlin

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

    Java

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

  3. Bạn cần lưu mã nhận dạng kênh để sau này thêm các chương trình vào kênh. Trích xuất mã nhận dạng kênh từ URI được trả về:

    Kotlin

    var channelId = ContentUris.parseId(channelUri)

    Java

    long channelId = ContentUris.parseId(channelUri);

  4. Bạn phải thêm biểu trưng cho kênh của mình. Sử dụng Uri hoặc Bitmap. Biểu tượng biểu trưng phải có kích thước 80 dp x 80 dp và phải mờ. Hình ảnh này được hiển thị dưới dạng mặt nạ hình tròn:

    Mặt nạ biểu tượng màn hình chính của TV

    Kotlin

    // 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)

    Java

    // 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. Tạo kênh mặc định (không bắt buộc): Khi ứng dụng tạo kênh đầu tiên, bạn có thể đặt kênh đó làm kênh mặc định để kênh đó xuất hiện ngay trên màn hình chính mà không cần người dùng thao tác. Mọi kênh khác mà bạn tạo sẽ không hiển thị cho đến khi người dùng chọn các kênh đó một cách rõ ràng.

    Kotlin

    TvContractCompat.requestChannelBrowsable(context, channelId)

    Java

    TvContractCompat.requestChannelBrowsable(context, channelId);

  6. Đặt kênh mặc định xuất hiện trước khi ứng dụng của bạn được mở. Bạn có thể thực hiện hành vi này bằng cách thêm một BroadcastReceiver để theo dõi hành động android.media.tv.action.INITIALIZE_PROGRAMS mà màn hình chính gửi sau khi cài đặt ứng dụng:

    <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>

    Khi cài đặt không qua cửa hàng ứng dụng trong quá trình phát triển, bạn có thể kiểm thử bước này bằng cách kích hoạt ý định thông qua adb, trong đó your.package.name/.YourReceiverName là BroadcastReceiver của ứng dụng:

    adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
    your.package.name/.YourReceiverName

    Trong một số ít trường hợp, ứng dụng của bạn có thể nhận được thông báo truyền tin cùng lúc với thời điểm người dùng khởi động ứng dụng. Hãy đảm bảo mã của bạn không cố gắng thêm kênh mặc định nhiều lần.

Cập nhật kênh

Quy trình cập nhật kênh rất giống với quy trình tạo kênh.

Sử dụng một Channel.Builder khác để đặt các thuộc tính cần thay đổi.

Sử dụng ContentResolver để cập nhật kênh. Sử dụng mã nhận dạng kênh mà bạn đã lưu khi kênh được thêm ban đầu:

Kotlin

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

Java

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

Để cập nhật biểu trưng của kênh, hãy sử dụng storeChannelLogo().

Xoá kênh

Kotlin

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

Java

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

Chương trình

Chương trình là các thẻ nội dung riêng lẻ xuất hiện trong một kênh. Bạn có thể xuất bản chương trình lên cả kênh tuỳ chỉnh của ứng dụng và kênh Xem tiếp theo do hệ thống quản lý.

Thêm chương trình vào kênh ứng dụng

Tạo PreviewProgram.Builder và đặt các thuộc tính của đối tượng đó:

Kotlin

val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId)

Java

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);

Thêm các thuộc tính khác tuỳ thuộc vào loại chương trình. (Để xem các thuộc tính có sẵn cho từng loại chương trình, hãy tham khảo bảng bên dưới.)

Chèn chương trình này vào nhà cung cấp:

Kotlin

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Java

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

Truy xuất mã chương trình để tham khảo sau:

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

Thêm chương trình vào kênh danh sách video phát tiếp theo

Để chèn chương trình vào kênh danh sách video phát tiếp theo, hãy xem phần Thêm chương trình vào kênh danh sách video phát tiếp theo.

Cập nhật chương trình

Bạn có thể thay đổi thông tin của chương trình. Ví dụ: Bạn có thể cập nhật giá thuê của một bộ phim hoặc cập nhật một thanh tiến trình cho biết thời lượng mà người dùng đã xem một chương trình.

Sử dụng PreviewProgram.Builder để đặt các thuộc tính bạn cần thay đổi, sau đó gọi getContentResolver().update để cập nhật chương trình. Chỉ định mã chương trình mà bạn đã lưu khi chương trình được thêm lần đầu:

Kotlin

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

Java

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

Xoá chương trình

Kotlin

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

Java

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

Xử lý thao tác của người dùng

Ứng dụng của bạn có thể giúp người dùng khám phá nội dung bằng cách cung cấp giao diện người dùng để hiển thị và thêm kênh. Ứng dụng của bạn cũng phải xử lý các hoạt động tương tác với kênh sau khi kênh xuất hiện trên màn hình chính.

Khám phá và thêm kênh

Ứng dụng của bạn có thể cung cấp một phần tử trên giao diện người dùng cho phép người dùng chọn và thêm kênh (ví dụ: nút yêu cầu thêm kênh).

Sau khi người dùng yêu cầu một kênh cụ thể, hãy thực thi mã này để xin phép người dùng thêm kênh đó vào giao diện người dùng trên màn hình chính:

Kotlin

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
}

Java

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
}

Hệ thống sẽ hiển thị một hộp thoại yêu cầu người dùng phê duyệt kênh. Xử lý kết quả của yêu cầu trong phương thức onActivityResult của hoạt động (Activity.RESULT_CANCELED hoặc Activity.RESULT_OK).

Sự kiện trên màn hình chính của Android TV

Khi người dùng tương tác với các chương trình và kênh do ứng dụng xuất bản, màn hình chính sẽ gửi ý định đến ứng dụng:

  • Màn hình chính sẽ gửi Uri được lưu trữ trong thuộc tính APP_LINK_INTENT_URI của một kênh đến ứng dụng khi người dùng chọn biểu trưng của kênh. Ứng dụng chỉ nên chạy giao diện người dùng chính hoặc một chế độ xem liên quan đến kênh đã chọn.
  • Màn hình chính sẽ gửi Uri được lưu trữ trong thuộc tính INTENT_URI của một chương trình đến ứng dụng khi người dùng chọn một chương trình. Ứng dụng sẽ phát nội dung đã chọn.
  • Người dùng có thể cho biết rằng họ không còn quan tâm đến một chương trình và muốn xoá chương trình đó khỏi giao diện người dùng của màn hình chính. Hệ thống sẽ xoá chương trình khỏi giao diện người dùng và gửi cho ứng dụng sở hữu chương trình một ý định (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED hoặc android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) cùng với mã nhận dạng của chương trình. Ứng dụng phải xoá chương trình khỏi trình cung cấp và KHÔNG được chèn lại chương trình đó.

Hãy nhớ tạo bộ lọc ý định cho tất cả Uris mà màn hình chính gửi cho hoạt động tương tác của người dùng; ví dụ:

<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>

Các yếu tố cần cân nhắc khác

  • Nhiều ứng dụng truyền hình yêu cầu người dùng đăng nhập. Trong trường hợp này, BroadcastReceiver lắng nghe android.media.tv.action.INITIALIZE_PROGRAMS nên đề xuất nội dung kênh cho người dùng chưa xác thực. Ví dụ: ban đầu, ứng dụng của bạn có thể hiển thị nội dung hay nhất hoặc nội dung hiện đang phổ biến. Sau khi người dùng đăng nhập, ứng dụng có thể hiển thị nội dung được cá nhân hoá. Đây là cơ hội tuyệt vời để các ứng dụng bán thêm cho người dùng trước khi họ đăng nhập.
  • Khi ứng dụng của bạn không chạy trên nền trước và bạn cần cập nhật kênh hoặc chương trình, hãy sử dụng JobScheduler để lên lịch cho công việc (xem JobScheduler và JobService).
  • Hệ thống có thể thu hồi quyền của nhà cung cấp ứng dụng nếu ứng dụng của bạn hoạt động không đúng cách (ví dụ: liên tục gửi dữ liệu rác cho nhà cung cấp). Hãy nhớ gói mã truy cập vào trình cung cấp bằng các mệnh đề try-catch để xử lý các ngoại lệ bảo mật.

  • Trước khi cập nhật chương trình và kênh, hãy truy vấn nhà cung cấp để biết dữ liệu bạn cần cập nhật và điều chỉnh dữ liệu. Ví dụ: không cần cập nhật chương trình mà người dùng muốn xoá khỏi giao diện người dùng. Sử dụng một công việc nền để chèn hoặc cập nhật dữ liệu của bạn vào trình cung cấp sau khi truy vấn dữ liệu hiện có, rồi yêu cầu phê duyệt cho các kênh của bạn. Bạn có thể chạy công việc này khi ứng dụng khởi động và bất cứ khi nào ứng dụng cần cập nhật dữ liệu.

Kotlin

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
                                }
                            }
              })

Java

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

  • Sử dụng URI riêng biệt cho tất cả hình ảnh (biểu trưng, biểu tượng, hình ảnh nội dung). Hãy nhớ sử dụng một URI khác khi bạn cập nhật hình ảnh. Tất cả hình ảnh đều được lưu vào bộ nhớ đệm. Nếu bạn không thay đổi Uri khi thay đổi hình ảnh, thì hình ảnh cũ sẽ tiếp tục xuất hiện.

  • Hãy nhớ rằng mệnh đề WHERE không được phép và các lệnh gọi đến nhà cung cấp có mệnh đề WHERE sẽ gửi một ngoại lệ bảo mật.

Thuộc tính

Phần này mô tả riêng các thuộc tính của kênh và chương trình.

Thuộc tính kênh

Bạn phải chỉ định các thuộc tính này cho mọi kênh:

Thuộc tính Ghi chú
LOẠI được đặt thành TYPE_PREVIEW.
DISPLAY_NAME được đặt thành tên của kênh.
APP_LINK_INTENT_URI Khi người dùng chọn biểu trưng của kênh, hệ thống sẽ gửi một ý định để bắt đầu một hoạt động trình bày nội dung liên quan đến kênh đó. Đặt thuộc tính này thành URI được dùng trong bộ lọc ý định cho hoạt động đó.

Ngoài ra, một kênh cũng có 6 trường dành riêng cho việc sử dụng ứng dụng nội bộ. Bạn có thể dùng các trường này để lưu trữ khoá hoặc các giá trị khác có thể giúp ứng dụng liên kết kênh với cấu trúc dữ liệu nội bộ:

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

Thuộc tính chương trình

Hãy xem từng trang để biết các thuộc tính cho từng loại chương trình:

Mã mẫu

Để tìm hiểu thêm về cách tạo ứng dụng tương tác với màn hình chính, cũng như thêm kênh và chương trình vào màn hình chính của Android TV, hãy xem lớp học lập trình về màn hình chính.

Trước
Giới thiệu về tính năng đề xuất nội dung trên TV
Tiếp
Thuộc tính chương trình video