หน้าจอหลักของ Android TV มี UI ที่แสดงเนื้อหาแนะนำเป็นตารางช่องและรายการ แต่ละแถวคือช่องทาง ช่องจะมี การ์ดสำหรับทุกรายการที่มีให้บริการในช่องนั้น
เอกสารนี้แสดงวิธีเพิ่มช่องและรายการลงในหน้าจอหลัก อัปเดตเนื้อหา จัดการการดำเนินการของผู้ใช้ และมอบประสบการณ์การใช้งานที่ดีที่สุดให้แก่ผู้ใช้ (หากต้องการเจาะลึกเกี่ยวกับ API ให้ลองใช้ Codelab หน้าจอหลักและดูเซสชัน Android TV ในงาน I/O 2017)
UI ของหน้าจอหลัก
แอปสามารถสร้างช่องใหม่ เพิ่ม นำออก และอัปเดตรายการในช่อง รวมถึงควบคุมลำดับของรายการในช่องได้ เช่น แอปสามารถสร้างช่องชื่อ "มีอะไรใหม่" และแสดงการ์ดสำหรับรายการที่เพิ่งพร้อมให้บริการ
แอปไม่สามารถควบคุมลำดับที่ช่องปรากฏในหน้าจอหลักได้ เมื่อแอปสร้างช่องใหม่ หน้าจอหลักจะเพิ่มช่องนั้นลงที่ด้านล่างของรายการช่อง ผู้ใช้สามารถจัดเรียงใหม่ ซ่อน และแสดงช่องได้
ช่องฟีดวิดีโอถัดไป
ฟีดวิดีโอถัดไปคือแถวที่ 2 ที่ปรากฏในหน้าจอหลักต่อจากแถวแอป ระบบจะสร้างและดูแลรักษาช่องทางนี้ แอปของคุณสามารถเพิ่มรายการลงในฟีดวิดีโอถัดไปได้ ดูข้อมูลเพิ่มเติมได้ที่เพิ่มรายการลงในฟีดวิดีโอถัดไป
ช่องทางของแอป
ช่องทางที่แอปของคุณสร้างขึ้นทั้งหมดจะเป็นไปตามวงจรนี้
- ผู้ใช้ค้นพบช่องในแอปของคุณและขอเพิ่มช่องลงในหน้าจอหลัก
- แอปจะสร้างช่องและเพิ่มลงใน
TvProvider(ณ จุดนี้ช่องจะยังไม่ปรากฏ) - แอปขอให้ระบบแสดงช่อง
- ระบบจะขอให้ผู้ใช้อนุมัติช่องใหม่
- ช่องใหม่จะปรากฏในแถวสุดท้ายของหน้าจอหลัก
ช่องเริ่มต้น
แอปของคุณสามารถเสนอช่องจำนวนเท่าใดก็ได้เพื่อให้ผู้ใช้เพิ่มลงในหน้าจอหลัก โดยปกติแล้ว ผู้ใช้จะต้องเลือกและอนุมัติแต่ละช่องก่อนที่ช่องจะปรากฏในหน้าจอหลัก ทุกแอปมีตัวเลือกในการสร้างช่องเริ่มต้น 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
หากต้องการสร้างช่อง ให้ทำตามขั้นตอนต่อไปนี้
สร้างเครื่องมือสร้างแชแนลและตั้งค่าแอตทริบิวต์ โปรดทราบว่าประเภทช่องทางต้องเป็น
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ไอคอนโลโก้ควรมีขนาด 80dp x 80dp และต้องทึบแสง โดยจะแสดงภายใต้มาสก์วงกลมดังนี้
// 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>เมื่อไซด์โหลดแอประหว่างการพัฒนา คุณสามารถทดสอบขั้นตอนนี้ได้โดยทริกเกอร์ 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หน้าจอหลัก