คู่มือนี้มีวิธีการสำหรับนักพัฒนาแอปในการผสานรวมเนื้อหาวิดีโอแนะนำโดยใช้ Engage SDK เพื่อแสดงประสบการณ์การแนะนำในแพลตฟอร์มต่างๆ ของ Google เช่น ทีวี อุปกรณ์เคลื่อนที่ และแท็บเล็ต
คำแนะนำใช้ประโยชน์จากคลัสเตอร์คำแนะนำเพื่อแสดงภาพยนตร์และรายการทีวีจากหลายแอปในการจัดกลุ่ม UI เดียว พาร์ทเนอร์นักพัฒนาแอปแต่ละรายสามารถออกอากาศเอนทิตีได้สูงสุด 25 รายการในแต่ละคลัสเตอร์คำแนะนำ และจะมีคลัสเตอร์คำแนะนำได้สูงสุด 7 รายการต่อคำขอ
งานก่อนเริ่มเวิร์กช็อป
โปรดทําตามขั้นตอนต่อไปนี้ก่อนเริ่มต้น 1. ยืนยันว่าแอปกำหนดเป้าหมายเป็น API ระดับ 19 ขึ้นไปสำหรับการผสานรวมนี้
เพิ่มคลัง
com.google.android.engage
ลงในแอปมี SDK แยกต่างหากสําหรับการผสานรวม 1 รายการสําหรับแอปบนอุปกรณ์เคลื่อนที่และ 1 รายการสําหรับแอปทีวี
สำหรับอุปกรณ์เคลื่อนที่
dependencies { implementation 'com.google.android.engage:engage-core:1.5.5 }
สำหรับทีวี
dependencies { implementation 'com.google.android.engage:engage-tv:1.0.2 }
ตั้งค่าสภาพแวดล้อมบริการ Engage เป็นเวอร์ชันที่ใช้งานจริงในไฟล์
AndroidManifest.xml
สำหรับ apk บนอุปกรณ์เคลื่อนที่
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
สำหรับ APK ของทีวี
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
ดำเนินการเผยแพร่ในบริการที่ทำงานอยู่เบื้องหน้า
เผยแพร่ข้อมูลคําแนะนําไม่เกินวันละครั้ง โดยทริกเกอร์โดยการดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้
- การเข้าสู่ระบบครั้งแรกของผู้ใช้ในวันนั้น (หรือ)
- เมื่อผู้ใช้เริ่มโต้ตอบกับแอปพลิเคชัน
การรวมระบบ
AppEngagePublishClient
เผยแพร่คลัสเตอร์คําแนะนํา ใช้เมธอด publishRecommendationClusters
เพื่อเผยแพร่ออบเจ็กต์คำแนะนำ
ใช้ isServiceAvailable()
2 เพื่อตรวจสอบว่าบริการพร้อมสำหรับการผสานรวมหรือไม่
val client = AppEngagePublishClient(context)
client.isServiceAvailable().addOnCompleteListener { task ->
if (task.isSuccessful) {
// Handle IPC call success
if(task.result) {
// Service is available on the device, proceed with content publish
// calls.
client.publishRecommendationClusters(recommendationRequest)
} else {
// Service is not available
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
กลุ่มคําแนะนําและคําขอเผยแพร่
กลุ่มคือการจัดกลุ่มเอนทิตีอย่างมีเหตุผล ตัวอย่างโค้ดต่อไปนี้อธิบายวิธีสร้างคลัสเตอร์ตามค่ากําหนดของคุณและวิธีสร้างคําขอเผยแพร่สําหรับคลัสเตอร์ทั้งหมด
// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Popular Movies")
.build()
// cluster for top searches
val recommendationCluster2 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Top Searches")
.build()
// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
.Builder()
.setSyncAcrossDevices(true)
.setAccountProfile(accountProfile)
.addRecommendationCluster(recommendationCluster1)
.addRecommendationCluster(recommendationCluster2)
.build()
สร้างโปรไฟล์บัญชี
ระบุข้อมูลบัญชีและโปรไฟล์เพื่อรับประสบการณ์การใช้งานที่ปรับเปลี่ยนในแบบของคุณบน Google TV ใช้ AccountProfile
เพื่อระบุข้อมูลต่อไปนี้
- รหัสบัญชี: ตัวระบุที่ไม่ซ้ำกันซึ่งแสดงถึงบัญชีของผู้ใช้ภายในแอปพลิเคชัน รหัสนี้อาจเป็นรหัสบัญชีจริงหรือรหัสที่มีการสร้างความสับสนอย่างเหมาะสม
- รหัสโปรไฟล์ (ไม่บังคับ): หากแอปพลิเคชันรองรับหลายโปรไฟล์ภายในบัญชีเดียว ให้ระบุตัวระบุที่ไม่ซ้ำกันสำหรับโปรไฟล์ผู้ใช้ที่เฉพาะเจาะจง
- ภาษา(ไม่บังคับ): คุณระบุภาษาที่ผู้ใช้ต้องการได้
ฟิลด์นี้จะมีประโยชน์หากคุณส่ง
MediaActionFeedEntity
ในRecommendationRequest
// If app only supports account
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.build();
// If app supports both account and profile
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.build();
// set Locale
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.setLocale("en-US")
.build();
เมื่อบริการได้รับคําขอ การดำเนินการต่อไปนี้จะเกิดขึ้นภายในธุรกรรมเดียว
- ระบบจะนำข้อมูล
RecommendationsCluster
ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาแอปออก - ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคําขอใน
RecommendationsCluster
ที่อัปเดตแล้ว ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะที่มีอยู่ไว้
การซิงค์หลายอุปกรณ์
Flag SyncAcrossDevices
จะควบคุมว่าจะแชร์ข้อมูลคลัสเตอร์คำแนะนำของผู้ใช้กับ Google TV และพร้อมใช้งานในอุปกรณ์ต่างๆ ของผู้ใช้ เช่น ทีวี โทรศัพท์ แท็บเล็ต หรือไม่ คุณต้องตั้งค่าเป็น "true" เพื่อให้คําแนะนําใช้งานได้
ขอความยินยอม
แอปพลิเคชันสื่อต้องระบุการตั้งค่าที่ชัดเจนเพื่อเปิดหรือปิดใช้การซิงค์ข้ามอุปกรณ์ อธิบายประโยชน์ให้แก่ผู้ใช้และจัดเก็บค่ากําหนดของผู้ใช้ในครั้งเดียว แล้วนําไปใช้ในpublishRecommendations
คําขอตามความเหมาะสม หากต้องการใช้ฟีเจอร์ที่ทำงานข้ามอุปกรณ์ให้ได้ประโยชน์สูงสุด ให้ยืนยันว่าแอปได้รับความยินยอมจากผู้ใช้และเปิดใช้ SyncAcrossDevices
เป็น true
ลบข้อมูลการค้นพบวิดีโอ
หากต้องการลบข้อมูลของผู้ใช้ออกจากเซิร์ฟเวอร์ Google TV ด้วยตนเองก่อนระยะเวลาการเก็บรักษามาตรฐาน 60 วัน ให้ใช้วิธีการ client.deleteClusters()
เมื่อได้รับคำขอ บริการจะลบข้อมูลการค้นพบวิดีโอที่มีอยู่ทั้งหมดสำหรับโปรไฟล์บัญชีหรือทั้งบัญชี
อาร์เรย์ค่าคงที่ DeleteReason
จะกำหนดเหตุผลในการลบข้อมูล
โค้ดต่อไปนี้จะนำคําแนะนําในการออกจากระบบออก
// If the user logs out from your media app, you must make the following call
// to remove recommendations data from the current google TV device,
// otherwise, the recommendations data persists on the current
// google TV device until 60 days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
.build()
)
// If the user revokes the consent to share data with Google TV,
// you must make the following call to remove recommendations data from
// all current google TV devices. Otherwise, the recommendations data persists
// until 60 days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
สร้างเอนทิตี
SDK ได้กําหนดเอนทิตีต่างๆ เพื่อแสดงรายการแต่ละประเภท ระบบรองรับเอนทิตีต่อไปนี้สําหรับคลัสเตอร์คําแนะนํา
MediaActionFeedEntity
MovieEntity
TvShowEntity
คำอธิบาย
ระบุคำอธิบายสั้นๆ สำหรับเอนทิตีแต่ละรายการ คำอธิบายนี้จะแสดงเมื่อผู้ใช้วางเมาส์เหนือเอนทิตีเพื่อให้รายละเอียดเพิ่มเติมแก่ผู้ใช้
URI การเล่นเฉพาะแพลตฟอร์ม
สร้าง URI การเล่นสำหรับแต่ละแพลตฟอร์มที่รองรับ ได้แก่ Android TV, Android หรือ iOS วิธีนี้ช่วยให้ระบบเลือก URI ที่เหมาะสมสำหรับการเล่นวิดีโอบนแพลตฟอร์มที่เกี่ยวข้องได้
ในกรณีที่พบได้ไม่บ่อยเมื่อ URI การเล่นเหมือนกันทุกแพลตฟอร์ม ให้ทำซ้ำสำหรับทุกแพลตฟอร์ม
// Required. Set this when you want recommended entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_TV)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
val playbackUriAndroid = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_IOS)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
.build()
val platformSpecificPlaybackUris =
Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)
// Provide appropriate rating for the system.
val contentRating = new RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
ภาพโปสเตอร์
รูปภาพโปสเตอร์ต้องมี URI และขนาดพิกเซล (ความสูงและความกว้าง) กําหนดเป้าหมายรูปแบบต่างๆ ด้วยการระบุรูปภาพโปสเตอร์หลายรูป แต่ตรวจสอบว่ารูปภาพทั้งหมดมีสัดส่วนภาพ 16:9 และความสูงขั้นต่ำ 200 พิกเซลเพื่อให้แสดงเอนทิตี "คําแนะนํา" ได้อย่างถูกต้อง โดยเฉพาะภายในพื้นที่บันเทิงของ Google รูปภาพที่มีความสูงน้อยกว่า 200 พิกเซลอาจไม่แสดง
Image image1 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
Image image2 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
.setImageHeightInPixel(640)
.setImageWidthInPixel(360)
.build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
เหตุผลของคําแนะนํา
(ไม่บังคับ) ระบุเหตุผลในการแนะนำที่ Google TV สามารถใช้เพื่อสร้างเหตุผลที่ควรแนะนำภาพยนตร์หรือรายการทีวีที่เฉพาะเจาะจงแก่ผู้ใช้
//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
.Builder()
.setNum(10) //any valid integer value
.build()
//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
.Builder()
.build()
//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
.Builder()
.build()
//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
.addSimilarWatchedTitleName("Movie or TV Show Title")
.addSimilarWatchedTitleName("Movie or TV Show Title")
.Builder()
.build()
//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
.Builder()
.build()
val watchAgain = RecommendationReasonWatchAgain
.Builder()
.build()
val fromUserWatchList = RecommendationReasonFromUserWatchlist
.Builder()
.build()
val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
.Builder()
.setTitleName("Movie or TV Show Title")
.build()
val generic = RecommendationReasonGeneric.Builder().build()
กรอบเวลาของการแสดง
หากต้องการให้เอนทิตีใช้งานได้ในเวลาจํากัด ให้กําหนดเวลาหมดอายุที่กําหนดเอง หากไม่มีเวลาหมดอายุที่ชัดเจน รายการต่างๆ จะหมดอายุและถูกลบโดยอัตโนมัติหลังจากผ่านไป 60 วัน ดังนั้น ให้ตั้งค่าเวลาหมดอายุเฉพาะในกรณีที่ต้องการให้เอนทิตีหมดอายุเร็วขึ้น ระบุกรอบเวลาความพร้อมให้บริการดังกล่าวหลายรายการ
val window1 = DisplayTimeWindow
.Builder()
.setStartTimeStampMillis(now()+ 1.days.toMillis())
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val window2 = DisplayTimeWindow
.Builder()
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)
DataFeedElementId
หากผสานรวมแคตตาล็อกสื่อหรือฟีดการดําเนินการของสื่อกับ Google TV แล้ว คุณไม่จําเป็นต้องสร้างเอนทิตีแยกต่างหากสําหรับภาพยนตร์หรือรายการทีวี แต่สามารถสร้างเอนทิตี MediaActionFeed ที่มีฟิลด์ DataFeedElementId ที่จําเป็นแทน รหัสนี้ต้องไม่ซ้ำกันและตรงกับรหัสในฟีดการดําเนินการกับสื่อ เนื่องจากจะช่วยระบุเนื้อหาฟีดที่ส่งผ่านและดําเนินการค้นหาเนื้อหาสื่อ
val id = "dataFeedEleemntId"
MovieEntity
ต่อไปนี้เป็นตัวอย่างการสร้าง MovieEntity
ที่มีฟิลด์ที่ต้องระบุทั้งหมด
val movieEntity = MovieEntity.Builder()
.setName("Movie name")
.setDescription("A sentence describing movie.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMills(72000000)
.build()
คุณสามารถให้ข้อมูลเพิ่มเติม เช่น ประเภท การจัดประเภทเนื้อหา วันที่เผยแพร่ เหตุผลที่แนะนำ และกรอบเวลาความพร้อมใช้งาน ซึ่ง Google TV อาจนำไปใช้เพื่อการแสดงหรือกรองที่มีประสิทธิภาพมากขึ้น
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build();
val contentRatings = Arrays.asList(rating1);
//Suppose release date is 11-02-2025
val releaseDate = 1739233800000L
val movieEntity = MovieEntity.Builder()
...
.addGenres(genres)
.setReleaseDateEpochMillis(releaseDate)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.build()
TvShowEntity
ต่อไปนี้เป็นตัวอย่างการสร้าง TvShowEntity
ที่มีฟิลด์ที่ต้องระบุทั้งหมด
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
.build();
ระบุข้อมูลเพิ่มเติม (ไม่บังคับ) เช่น ประเภท การจัดประเภทเนื้อหา เหตุผลที่แนะนำ ราคาของข้อเสนอ จำนวนซีซัน หรือกรอบเวลาความพร้อมให้บริการ ซึ่ง Google TV อาจนำไปใช้เพื่อการแสดงผลหรือการกรองที่มีประสิทธิภาพมากขึ้น
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build();
val price = Price.Builder()
.setCurrentPrice("$14.99")
.setStrikethroughPrice("$16.99")
.build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
...
.addGenres(genres)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.setSeasonCount(seasonCount)
.setPrice(price)
.build()
MediaActionFeedEntity
ต่อไปนี้เป็นตัวอย่างการสร้าง MediaActionFeedEntity
ที่มีฟิลด์ที่ต้องระบุทั้งหมด
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.build()
ระบุข้อมูลเพิ่มเติม (ไม่บังคับ) เช่น คำอธิบาย เหตุผลที่แนะนำ และกรอบเวลาในการแสดง ซึ่ง Google TV อาจนำไปใช้เพื่อการแสดงผลที่มีประสิทธิภาพมากขึ้นหรือเพื่อวัตถุประสงค์ในการกรอง
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setName("Movie name or TV Show name")
.setDescription("A sentence describing an entity")
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addPosterImages(images)
.build()
การทำตามขั้นตอนเหล่านี้จะช่วยให้นักพัฒนาแอปผสานรวมการแนะนำเนื้อหาวิดีโอลงใน Google TV ได้สำเร็จ ซึ่งจะช่วยเพิ่มการค้นพบและการมีส่วนร่วมของผู้ใช้ รวมถึงมอบประสบการณ์การรับชมที่สอดคล้องกันและปรับเปลี่ยนในแบบของคุณให้แก่ผู้ใช้ในทุกอุปกรณ์