ช่องต่างๆ ในหน้าจอหลัก

หน้าจอหลักของ Android TV มี UI ที่แสดงเนื้อหาแนะนำเป็นตารางช่องและรายการ แต่ละแถวคือช่องทาง ช่องจะมี การ์ดสำหรับทุกรายการที่มีให้บริการในช่องนั้น

หน้าจอหลักของ Android TV
หน้าจอหลักของ Android TV

เอกสารนี้แสดงวิธีเพิ่มช่องและรายการลงในหน้าจอหลัก อัปเดตเนื้อหา จัดการการดำเนินการของผู้ใช้ และมอบประสบการณ์การใช้งานที่ดีที่สุดให้แก่ผู้ใช้ (หากต้องการเจาะลึกเกี่ยวกับ API ให้ลองใช้ Codelab หน้าจอหลักและดูเซสชัน Android TV ในงาน I/O 2017)

UI ของหน้าจอหลัก

แอปสามารถสร้างช่องใหม่ เพิ่ม นำออก และอัปเดตรายการในช่อง รวมถึงควบคุมลำดับของรายการในช่องได้ เช่น แอปสามารถสร้างช่องชื่อ "มีอะไรใหม่" และแสดงการ์ดสำหรับรายการที่เพิ่งพร้อมให้บริการ

แอปไม่สามารถควบคุมลำดับที่ช่องปรากฏในหน้าจอหลักได้ เมื่อแอปสร้างช่องใหม่ หน้าจอหลักจะเพิ่มช่องนั้นลงที่ด้านล่างของรายการช่อง ผู้ใช้สามารถจัดเรียงใหม่ ซ่อน และแสดงช่องได้

ช่องฟีดวิดีโอถัดไป

ฟีดวิดีโอถัดไปคือแถวที่ 2 ที่ปรากฏในหน้าจอหลักต่อจากแถวแอป ระบบจะสร้างและดูแลรักษาช่องทางนี้ แอปของคุณสามารถเพิ่มรายการลงในฟีดวิดีโอถัดไปได้ ดูข้อมูลเพิ่มเติมได้ที่เพิ่มรายการลงในฟีดวิดีโอถัดไป

ช่องทางของแอป

ช่องทางที่แอปของคุณสร้างขึ้นทั้งหมดจะเป็นไปตามวงจรนี้

  1. ผู้ใช้ค้นพบช่องในแอปของคุณและขอเพิ่มช่องลงในหน้าจอหลัก
  2. แอปจะสร้างช่องและเพิ่มลงใน TvProvider (ณ จุดนี้ช่องจะยังไม่ปรากฏ)
  3. แอปขอให้ระบบแสดงช่อง
  4. ระบบจะขอให้ผู้ใช้อนุมัติช่องใหม่
  5. ช่องใหม่จะปรากฏในแถวสุดท้ายของหน้าจอหลัก

ช่องเริ่มต้น

แอปของคุณสามารถเสนอช่องจำนวนเท่าใดก็ได้เพื่อให้ผู้ใช้เพิ่มลงในหน้าจอหลัก โดยปกติแล้ว ผู้ใช้จะต้องเลือกและอนุมัติแต่ละช่องก่อนที่ช่องจะปรากฏในหน้าจอหลัก ทุกแอปมีตัวเลือกในการสร้างช่องเริ่มต้น 1 ช่อง ช่องเริ่มต้นเป็นช่องพิเศษเนื่องจากจะปรากฏในหน้าจอหลักโดยอัตโนมัติ ผู้ใช้ไม่จำเป็นต้องขออย่างชัดแจ้ง

สิ่งที่ต้องมีก่อน

หน้าจอหลักของ Android TV ใช้ API TvProvider ของ Android เพื่อจัดการช่องและรายการที่แอปของคุณสร้างขึ้น หากต้องการเข้าถึงข้อมูลของผู้ให้บริการ ให้เพิ่มสิทธิ์ต่อไปนี้ลงในไฟล์ Manifest ของแอป

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

ไลบรารีการสนับสนุน TvProvider ช่วยให้ใช้ผู้ให้บริการได้ง่ายขึ้น เพิ่มลงในทรัพยากร Dependency ในไฟล์ build.gradle

ดึงดูด

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

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

หากต้องการสร้างช่อง ให้ทำตามขั้นตอนต่อไปนี้

  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)

  2. แทรกช่องลงในผู้ให้บริการ:

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

  3. คุณต้องบันทึกรหัสช่องเพื่อเพิ่มรายการลงในช่องในภายหลัง ดึงข้อมูลรหัสช่องจาก URI ที่แสดงผล:

    var channelId = ContentUris.parseId(channelUri)

  4. คุณต้องเพิ่มโลโก้สำหรับช่อง ใช้ Uri หรือ Bitmap ไอคอนโลโก้ควรมีขนาด 80dp x 80dp และต้องทึบแสง โดยจะแสดงภายใต้มาสก์วงกลมดังนี้

    มาสก์ไอคอนหน้าจอหลักของทีวี

    // Choose one or the other.
    storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL.
    storeChannelLogo(context, channelId, logo)

  5. สร้างช่องเริ่มต้น (ไม่บังคับ): เมื่อแอปสร้างช่องแรก คุณสามารถกำหนดให้เป็นช่องเริ่มต้นเพื่อให้ปรากฏในหน้าจอหลักทันทีโดยที่ผู้ใช้ไม่ต้องดำเนินการใดๆ ผู้ใช้จะไม่เห็นช่องอื่นๆ ที่คุณสร้างจนกว่าจะเลือกช่องเหล่านั้นอย่างชัดเจน

    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
    

    ในบางกรณีซึ่งเกิดขึ้นไม่บ่อยนัก แอปของคุณอาจได้รับการออกอากาศในเวลาเดียวกับที่ผู้ใช้เริ่มแอป โปรดตรวจสอบว่าโค้ดของคุณไม่ได้พยายามเพิ่มแชแนลเริ่มต้นมากกว่า 1 ครั้ง

การอัปเดตช่อง

การอัปเดตช่องทางจะคล้ายกับการสร้างช่องทางมาก

ใช้ 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)

การจัดการการดำเนินการของผู้ใช้

แอปของคุณช่วยให้ผู้ใช้ค้นพบเนื้อหาได้โดยการจัดเตรียม UI เพื่อแสดงและเพิ่มช่อง แอปของคุณควรจัดการการโต้ตอบกับช่องหลังจากที่ปรากฏในหน้าจอหลักด้วย

การค้นหาและเพิ่มช่อง

แอปของคุณสามารถแสดงองค์ประกอบ UI ที่ให้ผู้ใช้เลือกและเพิ่มช่องของตนได้ (เช่น ปุ่มที่ขอให้เพิ่มช่อง)

หลังจากที่ผู้ใช้ขอช่องที่เฉพาะเจาะจง ให้เรียกใช้โค้ดนี้เพื่อขอสิทธิ์จากผู้ใช้ในการเพิ่มช่องลงใน UI ของหน้าจอหลัก

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

เมื่อผู้ใช้โต้ตอบกับรายการและช่องที่แอปเผยแพร่ หน้าจอหลักจะส่ง Intent ไปยังแอป ดังนี้

  • หน้าจอหลักจะส่ง Uri ที่จัดเก็บไว้ในแอตทริบิวต์ APP_LINK_INTENT_URI ของช่องไปยังแอปเมื่อผู้ใช้เลือกโลโก้ของช่อง แอปควรเปิด UI หลักหรือมุมมองที่เกี่ยวข้องกับช่องที่เลือกเท่านั้น
  • หน้าจอหลักจะส่ง Uri ที่จัดเก็บไว้ในแอตทริบิวต์ INTENT_URI ของรายการไปยังแอปเมื่อผู้ใช้เลือกรายการ แอปควรเล่นเนื้อหาที่เลือก
  • ผู้ใช้สามารถระบุได้ว่าไม่สนใจรายการใดรายการหนึ่งอีกต่อไปและต้องการนำรายการนั้นออกจาก UI ของหน้าจอหลัก ระบบจะนำรายการออกจาก UI และส่ง Intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED หรือ android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) พร้อมรหัสของรายการไปยังแอปที่เป็นเจ้าของรายการ แอปควรนำรายการออกจากผู้ให้บริการและไม่ควรใส่รายการนั้นกลับเข้าไปใหม่

ตรวจสอบว่าได้สร้างตัวกรอง Intent สำหรับ 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>

ข้อพิจารณาเพิ่มเติม

  • แอป TV หลายแอปกำหนดให้ผู้ใช้ต้องเข้าสู่ระบบ ในกรณีนี้ BroadcastReceiver ที่ฟัง android.media.tv.action.INITIALIZE_PROGRAMS ควรแนะนำ เนื้อหาช่องสำหรับผู้ใช้ที่ไม่ได้รับการตรวจสอบสิทธิ์ เช่น แอปของคุณสามารถแสดงเนื้อหาที่ดีที่สุดหรือเนื้อหายอดนิยมในตอนแรก หลังจากผู้ใช้เข้าสู่ระบบแล้ว แอปจะแสดงเนื้อหาที่ปรับเปลี่ยนในแบบของผู้ใช้ได้ นี่เป็นโอกาสที่ดีสำหรับแอปในการขายอัปเซลให้ผู้ใช้ก่อนที่จะเข้าสู่ระบบ
  • เมื่อแอปไม่ได้ทำงานอยู่เบื้องหน้าและคุณต้องการอัปเดตช่องหรือรายการ ให้ใช้ JobScheduler เพื่อกำหนดเวลางาน (ดูJobScheduler และ JobService)
  • ระบบสามารถเพิกถอนสิทธิ์ของผู้ให้บริการแอปได้หากแอปทำงานผิดปกติ (เช่น ส่งสแปมข้อมูลไปยังผู้ให้บริการอย่างต่อเนื่อง) ตรวจสอบว่าคุณรวมโค้ดที่เข้าถึงผู้ให้บริการด้วยคำสั่ง try-catch เพื่อจัดการข้อยกเว้นด้านความปลอดภัย
  • ก่อนอัปเดตรายการและช่อง ให้ค้นหาข้อมูลที่ต้องการอัปเดตจากผู้ให้บริการและตรวจสอบความถูกต้องของข้อมูล เช่น ไม่จำเป็นต้องอัปเดตโปรแกรมที่ผู้ใช้ต้องการนำออกจาก UI ใช้ Background Job ที่แทรกหรืออัปเดตข้อมูลของคุณในผู้ให้บริการหลังจากค้นหาข้อมูลที่มีอยู่แล้วขออนุมัติสำหรับช่องของคุณ คุณสามารถเรียกใช้งานนี้เมื่อแอปเริ่มทำงานและเมื่อใดก็ตามที่แอปต้องการอัปเดตข้อมูล

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 อื่นเมื่ออัปเดตรูปภาพ ระบบจะแคชรูปภาพทั้งหมด หากคุณไม่เปลี่ยน URI เมื่อเปลี่ยนรูปภาพ รูปภาพเก่าจะยังคงปรากฏต่อไป
  • โปรดทราบว่าระบบไม่อนุญาตให้ใช้ส่วนคำสั่ง WHERE และการเรียกไปยังผู้ให้บริการที่มีส่วนคำสั่ง WHERE จะทำให้เกิดข้อยกเว้นด้านความปลอดภัย

แอตทริบิวต์

ส่วนนี้จะอธิบายแอตทริบิวต์ของช่องทางและโปรแกรมแยกกัน

แอตทริบิวต์ของช่องทาง

คุณต้องระบุแอตทริบิวต์เหล่านี้สำหรับทุกช่องทาง

แอตทริบิวต์ หมายเหตุ
ประเภท ตั้งค่าเป็น TYPE_PREVIEW
DISPLAY_NAME เป็นชื่อของช่อง
APP_LINK_INTENT_URI เมื่อผู้ใช้เลือกโลโก้ของช่อง ระบบจะส่ง Intent เพื่อเริ่มกิจกรรมที่แสดงเนื้อหาที่เกี่ยวข้องกับช่อง ตั้งค่าแอตทริบิวต์นี้เป็น URI ที่ใช้ในตัวกรอง Intent สำหรับกิจกรรมนั้น

นอกจากนี้ ช่องยังมีฟิลด์อีก 6 ฟิลด์ที่สงวนไว้สำหรับการใช้งานแอปภายใน คุณสามารถใช้ช่องเหล่านี้เพื่อจัดเก็บคีย์หรือค่าอื่นๆ ที่ช่วยให้แอปแมปช่องกับโครงสร้างข้อมูลภายในได้

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

แอตทริบิวต์ของโปรแกรม

ดูหน้าเว็บแต่ละหน้าสำหรับแอตทริบิวต์ของโปรแกรมแต่ละประเภท

โค้ดตัวอย่าง

ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างแอปที่โต้ตอบกับหน้าจอหลักและเพิ่มช่องและโปรแกรมลงในหน้าจอหลักของ Android TV ได้ที่Codelabหน้าจอหลัก