คู่มือการผสานรวม Engage SDK สําหรับทีวี

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

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

ก่อนเริ่มต้น ให้ทำตามขั้นตอนต่อไปนี้

  1. อัปเดตเป็น API เป้าหมาย 19 ขึ้นไป

  2. เพิ่มไลบรารี com.google.android.engage ลงในแอป

    มี SDK แยกต่างหากให้ใช้ในการผสานรวม โดย SDK หนึ่งสำหรับแอปบนอุปกรณ์เคลื่อนที่ และอีก SDK หนึ่งสำหรับแอปทีวี

    อุปกรณ์เคลื่อนที่

    
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }

    ทีวี

    
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }

  3. ตั้งค่าสภาพแวดล้อมของบริการ Engage เป็นการใช้งานจริงในไฟล์ AndroidManifest.xml

    อุปกรณ์เคลื่อนที่

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION" />

    ทีวี

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION" />

  4. เพิ่มสิทธิ์สำหรับ WRITE_EPG_DATA สำหรับ APK ของทีวี

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

  5. ยืนยันการเผยแพร่เนื้อหาที่เชื่อถือได้โดยใช้บริการเบื้องหลัง เช่น androidx.work เพื่อกำหนดเวลา

  6. เผยแพร่ข้อมูลการดูต่อเมื่อเกิดเหตุการณ์ต่อไปนี้ เพื่อมอบประสบการณ์การรับชมที่ราบรื่น

    1. การเข้าสู่ระบบครั้งแรก: เมื่อผู้ใช้เข้าสู่ระบบเป็นครั้งแรก ให้เผยแพร่ข้อมูลเพื่อให้แน่ใจว่าประวัติการดูของผู้ใช้พร้อมใช้งานทันที
    2. การสร้างหรือการสลับโปรไฟล์ (แอปแบบหลายโปรไฟล์): หากแอปของคุณรองรับ หลายโปรไฟล์ ให้เผยแพร่ข้อมูลเมื่อผู้ใช้สร้างหรือสลับโปรไฟล์
    3. การหยุดเล่นวิดีโอชั่วคราว: เผยแพร่ข้อมูลเมื่อผู้ใช้หยุดหรือหยุดวิดีโอชั่วคราว หรือเมื่อแอปปิดระหว่างการเล่น เพื่อช่วยให้ผู้ใช้เล่นต่อจากที่ค้างไว้
    4. การอัปเดตถาด "ดูต่อ" (หากรองรับ): เมื่อผู้ใช้นำรายการออกจากถาด "ดูต่อ" ให้แสดงการเปลี่ยนแปลงนั้นด้วยการเผยแพร่ข้อมูลที่อัปเดตแล้ว
    5. การดูวิดีโอจนจบ
      1. สำหรับภาพยนตร์ ให้นำภาพยนตร์ที่ดูจบแล้วออกจากถาด "รับชมต่อ" หากภาพยนตร์เป็นส่วนหนึ่งของซีรีส์ ให้เพิ่มภาพยนตร์เรื่องถัดไปเพื่อดึงดูดความสนใจของผู้ใช้
      2. สำหรับตอนต่างๆ ให้นำตอนที่ดูจบแล้วออกและเพิ่มตอนถัดไปในซีรีส์ (หากมี) เพื่อกระตุ้นให้ดูต่อ

การรวมระบบ

AccountProfile

หากต้องการอนุญาตให้ใช้ประสบการณ์ "ดูต่อ" ที่ปรับเปลี่ยนในแบบของคุณบน Google TV โปรดระบุข้อมูลบัญชีและโปรไฟล์ ใช้ AccountProfile เพื่อระบุข้อมูลต่อไปนี้

  1. รหัสบัญชี: ตัวระบุที่ไม่ซ้ำซึ่งแสดงถึงบัญชีของผู้ใช้ภายในแอปพลิเคชันของคุณ ซึ่งอาจเป็นรหัสบัญชีจริงหรือเวอร์ชันที่ ปิดบังอย่างเหมาะสมก็ได้

  2. รหัสโปรไฟล์ (ไม่บังคับ): หากแอปพลิเคชันรองรับหลายโปรไฟล์ภายใน บัญชีเดียว ให้ระบุตัวระบุที่ไม่ซ้ำกันสำหรับโปรไฟล์ผู้ใช้ที่เฉพาะเจาะจง (อีกครั้ง โปรไฟล์จริงหรือโปรไฟล์ที่ผ่านการปกปิด)

// If your app only supports account
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .build()

// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .setProfileId("your_users_profile_id")
    .build()

สร้างเอนทิตี

SDK ได้กำหนดเอนทิตีต่างๆ เพื่อแสดงรายการแต่ละประเภท คลัสเตอร์ Continuation รองรับเอนทิตีต่อไปนี้

  1. MovieEntity
  2. TvEpisodeEntity
  3. LiveStreamingVideoEntity
  4. VideoClipEntity

ระบุ URI และภาพโปสเตอร์เฉพาะแพลตฟอร์มสำหรับเอนทิตีเหล่านี้

นอกจากนี้ ให้สร้าง URI การเล่นสําหรับแต่ละแพลตฟอร์ม เช่น Android TV, Android หรือ iOS หากยังไม่ได้สร้าง ดังนั้นเมื่อผู้ใช้ดูต่อในแต่ละแพลตฟอร์ม แอปจะใช้ URI การเล่นที่กำหนดเป้าหมายเพื่อเล่นเนื้อหาวิดีโอ

// Required. Set this when you want continue watching 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()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
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 continue watching 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)

รูปภาพโปสเตอร์ต้องมี URI และขนาดพิกเซล (ความสูงและความกว้าง) กำหนดเป้าหมาย รูปแบบที่แตกต่างกันโดยระบุภาพโปสเตอร์หลายภาพ แต่ตรวจสอบว่าภาพทั้งหมด มีสัดส่วนภาพ 16:9 และมีความสูงขั้นต่ำ 200 พิกเซลเพื่อให้แสดงผลเอนทิตี "ดูต่อ" ได้อย่างถูกต้อง โดยเฉพาะภายในพื้นที่ความบันเทิงของ Google ระบบอาจไม่แสดงรูปภาพที่มีความสูงน้อยกว่า 200 พิกเซล 

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)
MovieEntity

ตัวอย่างนี้แสดงวิธีสร้าง MovieEntity โดยมีช่องที่จำเป็นทั้งหมด

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .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)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

เอนทิตีจะยังคงพร้อมใช้งานโดยอัตโนมัติเป็นเวลา 60 วัน เว้นแต่คุณจะระบุเวลาหมดอายุที่สั้นกว่า ตั้งค่าการหมดอายุที่กำหนดเองเฉพาะในกรณีที่คุณต้องการนำเอนทิตีออกก่อนระยะเวลาเริ่มต้นนี้

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()
TvEpisodeEntity

ตัวอย่างนี้แสดงวิธีสร้าง TvEpisodeEntity โดยมีฟิลด์ที่จำเป็นทั้งหมด 

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

ระบบจะขยายสตริงหมายเลขตอน (เช่น "2") และสตริงหมายเลขซีซัน (เช่น "1") เป็นรูปแบบที่เหมาะสมก่อนที่จะแสดงใน การ์ดดูต่อ โปรดทราบว่าควรเป็นสตริงตัวเลข อย่าใส่ "e2", หรือ "episode 2" หรือ "s1" หรือ "season 1"

หากรายการทีวีมีเพียงซีซันเดียว ให้ตั้งหมายเลขซีซันเป็น 1

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

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()
VideoClipEntity

ต่อไปนี้เป็นตัวอย่างการสร้าง VideoClipEntity โดยมีช่องที่ต้องระบุทั้งหมด

VideoClipEntity แสดงถึงคลิปที่ผู้ใช้สร้างขึ้น เช่น วิดีโอ YouTube

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

คุณเลือกตั้งค่าผู้สร้าง รูปภาพของผู้สร้าง เวลาที่สร้างเป็นมิลลิวินาที หรือกรอบเวลาความพร้อมได้

LiveStreamingVideoEntity

ต่อไปนี้เป็นตัวอย่างการสร้าง LiveStreamingVideoEntity โดยมีฟิลด์ที่จำเป็นทั้งหมด 

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

คุณเลือกตั้งเวลาเริ่มต้น ผู้แพร่ภาพ ไอคอนผู้แพร่ภาพ หรือ กรอบเวลาความพร้อมใช้งานสำหรับเอนทิตีสตรีมแบบสดได้

ดูข้อมูลโดยละเอียดเกี่ยวกับแอตทริบิวต์และข้อกำหนดได้ที่เอกสารอ้างอิง API

ระบุข้อมูลคลัสเตอร์การดำเนินการต่อ

AppEngagePublishClient มีหน้าที่รับผิดชอบในการเผยแพร่คลัสเตอร์การดำเนินการต่อ คุณใช้วิธี publishContinuationCluster() เพื่อเผยแพร่ออบเจ็กต์ ContinuationCluster

ก่อนอื่น คุณควรใช้ isServiceAvailable() เพื่อตรวจสอบว่าบริการพร้อมสำหรับการผสานรวมหรือไม่

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

เมื่อบริการได้รับคำขอ ระบบจะดำเนินการต่อไปนี้ภายในธุรกรรมเดียว

  • ระบบจะนำข้อมูล ContinuationCluster ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาแอปออก
  • ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคำขอในContinuationClusterที่อัปเดต

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

API การเผยแพร่เป็น API การแทรก/อัปเดต ซึ่งจะแทนที่เนื้อหาที่มีอยู่ หากต้องการอัปเดตเอนทิตีที่เฉพาะเจาะจงใน ContinuationCluster คุณจะต้อง เผยแพร่เอนทิตีทั้งหมดอีกครั้ง

ควรระบุข้อมูล ContinuationCluster สำหรับบัญชีของผู้ใหญ่เท่านั้น เผยแพร่เฉพาะเมื่อ AccountProfile เป็นของบุคคลที่บรรลุนิติภาวะแล้ว

การซิงค์ข้ามอุปกรณ์

SyncAcrossDevices flag ควบคุมว่าระบบจะซิงค์ข้อมูล ContinuationCluster ของผู้ใช้ในอุปกรณ์ต่างๆ เช่น ทีวี โทรศัพท์ แท็บเล็ต ฯลฯ หรือไม่ การซิงค์ข้ามอุปกรณ์จะปิดใช้โดยค่าเริ่มต้น

ค่า:

  • จริง: ระบบจะแชร์ข้อมูล ContinuationCluster ในอุปกรณ์ทั้งหมดของผู้ใช้เพื่อให้ ประสบการณ์การรับชมราบรื่น เราขอแนะนำให้ใช้ตัวเลือกนี้เพื่อประสบการณ์การใช้งานข้ามอุปกรณ์ที่ดีที่สุด
  • false: ข้อมูล ContinuationCluster จะจำกัดไว้ในอุปกรณ์ปัจจุบัน

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

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

หากต้องการใช้ฟีเจอร์ข้ามอุปกรณ์ให้เกิดประโยชน์สูงสุด โปรดยืนยันว่าแอปได้รับ ความยินยอมจากผู้ใช้และเปิดใช้ SyncAcrossDevices กับ true ซึ่งช่วยให้เนื้อหาสามารถซิงค์ในอุปกรณ์ต่างๆ ได้อย่างราบรื่น ส่งผลให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ดีขึ้นและมีส่วนร่วมมากขึ้น ตัวอย่างเช่น พาร์ทเนอร์ที่ใช้ฟีเจอร์นี้มีการคลิก "ดูต่อ" เพิ่มขึ้น 40% เนื่องจากระบบแสดงเนื้อหาในอุปกรณ์หลายเครื่อง

ลบข้อมูลการค้นพบวิดีโอ

หากต้องการลบข้อมูลของผู้ใช้จากเซิร์ฟเวอร์ Google TV ด้วยตนเองก่อนระยะเวลาเก็บรักษามาตรฐาน 60 วัน ให้ใช้วิธีการ client.deleteClusters() เมื่อได้รับคำขอ บริการจะลบข้อมูลการค้นพบวิดีโอที่มีอยู่ทั้งหมดสำหรับโปรไฟล์บัญชีหรือทั้งบัญชี

การแจงนับ DeleteReason จะกำหนดเหตุผลในการลบข้อมูล โค้ดต่อไปนี้จะนำข้อมูลการดูต่อออกเมื่อออกจากระบบ


// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

การทดสอบ

ใช้แอปการยืนยันเพื่อยืนยันว่าการผสานรวม Engage SDK ทำงาน อย่างถูกต้อง แอปพลิเคชัน Android นี้มีเครื่องมือที่จะช่วยคุณ ยืนยันข้อมูลและยืนยันว่ามีการจัดการ Intent การออกอากาศอย่างถูกต้อง

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

  • ตั้งค่า Engage Service Flag สำหรับบิลด์ที่ไม่ใช่เวอร์ชันที่ใช้งานจริงในไฟล์ Manifest ของ Android ของแอปเท่านั้น
  • ติดตั้งและเปิดแอป Engage Verify
  • หาก isServiceAvailable เป็น false ให้คลิกปุ่ม "เปิด/ปิด" เพื่อเปิดใช้
  • ป้อนชื่อแพ็กเกจของแอปเพื่อดูข้อมูลที่เผยแพร่โดยอัตโนมัติเมื่อเริ่มเผยแพร่
  • ทดสอบการดำเนินการต่อไปนี้ในแอป
    • ลงชื่อเข้าใช้
    • สลับระหว่างโปรไฟล์(หากมี)
    • เริ่มเล่น จากนั้นหยุดวิดีโอชั่วคราว หรือกลับไปที่หน้าแรก
    • ปิดแอปขณะเล่นวิดีโอ
    • นำรายการออกจากแถว "ดูต่อ" (หากระบบรองรับ)
  • หลังจากดำเนินการแต่ละอย่างแล้ว ให้ยืนยันว่าแอปของคุณเรียกใช้ publishContinuationClusters API และข้อมูลแสดงอย่างถูกต้องใน แอปยืนยัน

  • แอปการยืนยันจะแสดงเครื่องหมายถูกสีเขียว "เรียบร้อย" สำหรับเอนทิตีที่ติดตั้งใช้งานอย่างถูกต้อง

    ภาพหน้าจอแสดงการยืนยันแอปสำเร็จ
    รูปที่ 1 ความสำเร็จในการใช้แอปยืนยัน

  • แอปยืนยันจะแจ้งรายการที่มีปัญหา

    ภาพหน้าจอข้อผิดพลาดของแอปยืนยัน
    รูปที่ 2 ข้อผิดพลาดของแอปยืนยัน

  • หากต้องการแก้ปัญหาเอนทิตีที่มีข้อผิดพลาด ให้ใช้รีโมตทีวีเพื่อเลือกและคลิก เอนทิตีในแอปยืนยัน ปัญหาที่เฉพาะเจาะจงจะแสดง และไฮไลต์เป็นสีแดงเพื่อให้คุณตรวจสอบ (ดูตัวอย่างด้านล่าง)

    รายละเอียดข้อผิดพลาดของแอปยืนยัน
    รูปที่ 3 รายละเอียดข้อผิดพลาดของแอปยืนยัน

REST API

Engage SDK มี REST API เพื่อมอบประสบการณ์การดูต่อที่สอดคล้องกัน ในแพลตฟอร์มที่ไม่ใช่ Android เช่น iOS, Roku TV API นี้ช่วยให้ นักพัฒนาแอปอัปเดตสถานะ "ดูต่อ" สำหรับผู้ใช้ที่เลือกใช้จากแพลตฟอร์มที่ไม่ใช่ Android ได้

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

  • คุณต้องผสานรวมที่อิงตาม Engage SDK ในอุปกรณ์ให้เสร็จก่อน ขั้นตอนนี้มีความสำคัญอย่างยิ่งในการสร้างความเชื่อมโยงที่จำเป็นระหว่างรหัสผู้ใช้ของ Google กับ AccountProfile ของแอป
  • การเข้าถึงและการตรวจสอบสิทธิ์ API: หากต้องการดูและเปิดใช้ API ในโปรเจ็กต์ Google Cloud คุณต้องผ่านกระบวนการรายการที่อนุญาต คำขอ API ทั้งหมดต้องมีการตรวจสอบสิทธิ์

การขอรับสิทธิ์เข้าถึง

หากต้องการมีสิทธิ์เข้าถึงเพื่อดูและเปิดใช้ API ในคอนโซล Google Cloud คุณต้องลงทะเบียนบัญชี

  1. ควรมีรหัสลูกค้า Google Workspace หากไม่มี คุณอาจต้องตั้งค่า Google Workspace รวมถึงบัญชี Google ที่ต้องการใช้เพื่อเรียก API
  2. ตั้งค่าบัญชีด้วย Google Cloud Console โดยใช้อีเมลที่เชื่อมโยงกับ Google Workspace
  3. สร้างโปรเจ็กต์ใหม่
  4. สร้างบัญชีบริการสำหรับการตรวจสอบสิทธิ์ API เมื่อสร้างบัญชีบริการแล้ว คุณจะมี 2 รายการต่อไปนี้
    • รหัสบัญชีบริการ
    • ไฟล์ JSON ที่มีคีย์บัญชีบริการ เก็บไฟล์นี้ไว้ให้ปลอดภัย เนื่องจากคุณจะต้องใช้ไฟล์นี้เพื่อตรวจสอบสิทธิ์ไคลเอ็นต์กับ API ในภายหลัง
  5. ตอนนี้ Workspace และบัญชี Google ที่เชื่อมโยงจะใช้ REST API ได้แล้ว เมื่อการเปลี่ยนแปลงมีผลแล้ว คุณจะได้รับการแจ้งเตือนว่า API พร้อมให้บัญชีบริการเรียกใช้หรือไม่
  6. ทำตามขั้นตอนเหล่านี้เพื่อเตรียมพร้อมสำหรับการเรียก API ที่ได้รับมอบสิทธิ์

คลัสเตอร์การเผยแพร่ต่อเนื่อง

หากต้องการเผยแพร่ข้อมูลวิดีโอ Discovery ให้ส่งคำขอ POST ไปยัง publishContinuationCluster API โดยใช้ไวยากรณ์ต่อไปนี้

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

สถานที่:

  • package_name: ชื่อแพ็กเกจของผู้ให้บริการสื่อ
  • accountId: รหัสที่ไม่ซ้ำกันสำหรับบัญชีของผู้ใช้ในระบบของคุณ โดยต้องตรงกับ accountId ที่ใช้ในเส้นทางบนอุปกรณ์
  • profileId: รหัสที่ไม่ซ้ำสำหรับโปรไฟล์ของผู้ใช้ภายในบัญชีในระบบของคุณ โดยต้องตรงกับ profileId ที่ใช้ในเส้นทางบนอุปกรณ์

URL ของบัญชีที่ไม่มีโปรไฟล์คือ

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

เพย์โหลดของคำขอจะแสดงในช่อง entities entities แสดงรายการเอนทิตีเนื้อหาซึ่งอาจเป็น MovieEntity หรือ TVEpisodeEntity ฟิลด์นี้เป็นฟิลด์ที่ต้องระบุ

เนื้อความของคำขอ

Field

ประเภท

ต้องระบุ

คำอธิบาย

เอนทิตี

รายการออบเจ็กต์ MediaEntity

ใช่

รายการเอนทิตีเนื้อหา (สูงสุด 5 รายการ) ระบบจะเก็บเฉพาะ 5 รายการแรก และทิ้งรายการที่เหลือ อนุญาตให้ใช้รายการว่างเพื่อระบุว่าผู้ใช้ดู เอนทิตีทั้งหมดเสร็จแล้ว

ฟิลด์ entities มี movieEntity และ tvEpisodeEntity ของแต่ละรายการ

Field

ประเภท

ต้องระบุ

คำอธิบาย

movieEntity

MovieEntity

ใช่

ออบเจ็กต์ที่แสดงภาพยนตร์ภายใน ContinuationCluster

tvEpisodeEntity

TvEpisodeEntity

ใช่

ออบเจ็กต์ที่แสดงตอนทีวีภายใน ContinuationCluster

ออบเจ็กต์แต่ละรายการในอาร์เรย์เอนทิตีต้องเป็นประเภท MediaEntity ที่ใช้ได้ประเภทใดประเภทหนึ่ง กล่าวคือ MovieEntity และ TvEpisodeEntity พร้อมด้วยฟิลด์ทั่วไปและฟิลด์เฉพาะประเภท

ข้อมูลโค้ดต่อไปนี้แสดงเพย์โหลดของเนื้อหาคำขอสำหรับ API ของ publishContinuationCluster

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

ลบข้อมูลการค้นพบวิดีโอ

ใช้ clearClusters API เพื่อนำข้อมูลการค้นพบวิดีโอออก

ใช้ URL ของ POST เพื่อนำเอนทิตีออกจากข้อมูลการค้นพบวิดีโอ หากต้องการลบข้อมูลคลัสเตอร์การดำเนินการต่อ ให้ส่งคำขอ POST ไปยัง clearClusters API โดยใช้ไวยากรณ์ต่อไปนี้

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

สถานที่:

  • package_name: ชื่อแพ็กเกจของผู้ให้บริการสื่อ
  • accountId: รหัสที่ไม่ซ้ำกันสำหรับบัญชีของผู้ใช้ในระบบของคุณ โดยต้องตรงกับ accountId ที่ใช้ในเส้นทางบนอุปกรณ์
  • profileId: รหัสที่ไม่ซ้ำสำหรับโปรไฟล์ของผู้ใช้ภายในบัญชีในระบบของคุณ โดยต้องตรงกับ profileId ที่ใช้ในเส้นทางบนอุปกรณ์

เพย์โหลดสำหรับ clearClusters API มีฟิลด์เดียวเท่านั้นคือ reason ซึ่งมี DeleteReason ที่ระบุเหตุผลในการนำข้อมูลออก 

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

การทดสอบ

หลังจากโพสต์ข้อมูลเรียบร้อยแล้ว ให้ใช้บัญชีทดสอบผู้ใช้เพื่อยืนยันว่าเนื้อหาที่คาดไว้ปรากฏในแถว "ดูต่อ" ในแพลตฟอร์ม Google เป้าหมาย เช่น Google TV และแอป Google TV บนอุปกรณ์เคลื่อนที่ Android และ iOS

ในการทดสอบ ให้รอการเผยแพร่ที่สมเหตุสมผลเป็นเวลา 2-3 นาที และปฏิบัติตาม ข้อกำหนดในการดู เช่น ดูภาพยนตร์บางส่วนหรือดู ตอนจนจบ ดูรายละเอียดได้ในหลักเกณฑ์ของ "ดูต่อ" สำหรับนักพัฒนาแอป