Engage SDK สำหรับการแนะนำวิดีโอ

คู่มือนี้มีวิธีการสำหรับนักพัฒนาแอปในการผสานรวมเนื้อหาวิดีโอแนะนำโดยใช้ Engage SDK เพื่อแสดงประสบการณ์การแนะนำในแพลตฟอร์มต่างๆ ของ Google เช่น ทีวี อุปกรณ์เคลื่อนที่ และแท็บเล็ต

คำแนะนำใช้ประโยชน์จากคลัสเตอร์คำแนะนำเพื่อแสดงภาพยนตร์และรายการทีวีจากหลายแอปในการจัดกลุ่ม UI เดียว พาร์ทเนอร์นักพัฒนาแอปแต่ละรายสามารถออกอากาศเอนทิตีได้สูงสุด 25 รายการในแต่ละคลัสเตอร์คำแนะนำ และจะมีคลัสเตอร์คำแนะนำได้สูงสุด 7 รายการต่อคำขอ

งานก่อนเริ่มเวิร์กช็อป

โปรดทําตามขั้นตอนต่อไปนี้ก่อนเริ่มต้น 1. ยืนยันว่าแอปกำหนดเป้าหมายเป็น API ระดับ 19 ขึ้นไปสำหรับการผสานรวมนี้

  1. เพิ่มคลัง 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
      }
    
  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>
    
  3. ดำเนินการเผยแพร่ในบริการที่ทำงานอยู่เบื้องหน้า

  4. เผยแพร่ข้อมูลคําแนะนําไม่เกินวันละครั้ง โดยทริกเกอร์โดยการดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

    1. การเข้าสู่ระบบครั้งแรกของผู้ใช้ในวันนั้น (หรือ)
    2. เมื่อผู้ใช้เริ่มโต้ตอบกับแอปพลิเคชัน

การรวมระบบ

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 เพื่อระบุข้อมูลต่อไปนี้

  1. รหัสบัญชี: ตัวระบุที่ไม่ซ้ำกันซึ่งแสดงถึงบัญชีของผู้ใช้ภายในแอปพลิเคชัน รหัสนี้อาจเป็นรหัสบัญชีจริงหรือรหัสที่มีการสร้างความสับสนอย่างเหมาะสม
  2. รหัสโปรไฟล์ (ไม่บังคับ): หากแอปพลิเคชันรองรับหลายโปรไฟล์ภายในบัญชีเดียว ให้ระบุตัวระบุที่ไม่ซ้ำกันสำหรับโปรไฟล์ผู้ใช้ที่เฉพาะเจาะจง
  3. ภาษา(ไม่บังคับ): คุณระบุภาษาที่ผู้ใช้ต้องการได้ ฟิลด์นี้จะมีประโยชน์หากคุณส่ง 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 ได้กําหนดเอนทิตีต่างๆ เพื่อแสดงรายการแต่ละประเภท ระบบรองรับเอนทิตีต่อไปนี้สําหรับคลัสเตอร์คําแนะนํา

  1. MediaActionFeedEntity
  2. MovieEntity
  3. 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 ได้สำเร็จ ซึ่งจะช่วยเพิ่มการค้นพบและการมีส่วนร่วมของผู้ใช้ รวมถึงมอบประสบการณ์การรับชมที่สอดคล้องกันและปรับเปลี่ยนในแบบของคุณให้แก่ผู้ใช้ในทุกอุปกรณ์