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

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

สิ่งที่ต้องเตรียมก่อนดำเนินการ

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

1. อัปเดตเป็น API เป้าหมายระดับตั้งแต่ 19 ขึ้นไป

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

   มี SDK แยกต่างหากให้ใช้ในการผสานรวม โดย SDK หนึ่งสำหรับแอปบนมือถือ และอีก SDK หนึ่งสำหรับแอป TV

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

   
     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. สำหรับตอนต่างๆ ให้นำตอนที่ดูจบแล้วออกและเพิ่มตอนถัดไปในซีรีส์ (หากมี) เพื่อกระตุ้นให้ดูต่อ

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

แอปตัวอย่างนี้แสดงวิธีที่นักพัฒนาแอปสามารถผสานรวมกับ API การค้นพบวิดีโอเพื่อส่งข้อมูลผู้ใช้ที่ปรับตามโปรไฟล์ไปยัง Google แอปตัวอย่างยังแสดงวิธีสร้างโมดูลทั่วไปที่นำเข้าได้ทั้งในแอปมือถือและแอป TV, เวลาที่ควรเรียกใช้ API การเผยแพร่และการลบ รวมถึงวิธีใช้ Worker เพื่อเรียกใช้ API การเผยแพร่และการลบ

การผสานรวม

AccountProfile

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

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

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

// 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 ได้กำหนดเอนทิตีต่างๆ เพื่อแสดงรายการแต่ละประเภท คลัสเตอร์ความต่อเนื่องจะรองรับเอนทิตีต่อไปนี้

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 พิกเซล เพื่อให้แสดงผลเอนทิตี "รับชมต่อ" ได้อย่างถูกต้องโดยเฉพาะภายใน Entertainment Space ของ 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 ของผู้ใช้ในอุปกรณ์ต่างๆ เช่น ทีวี โทรศัพท์ แท็บเล็ต ฯลฯ หรือไม่ การซิงค์ข้ามอุปกรณ์จะปิดใช้โดยค่าเริ่มต้น

ค่า:

• true: ระบบจะแชร์ข้อมูล 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 Enum จะกำหนดเหตุผลในการลบข้อมูล โค้ดต่อไปนี้จะนำข้อมูลการรับชมต่อออกเมื่อออกจากระบบ

// 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 ทำงานอย่างถูกต้อง แอปยืนยันมีเครื่องมือที่จะช่วยคุณยืนยันข้อมูลและยืนยันว่ามีการจัดการ Intent การออกอากาศอย่างถูกต้อง

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

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

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

  

• แอปยืนยันจะแจ้งเอนทิตีที่มีปัญหา

  

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

  

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 ที่ได้รับมอบสิทธิ์

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

หากต้องการเผยแพร่ข้อมูลการค้นพบวิดีโอ ให้ส่งคำขอ 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 อย่างใดอย่างหนึ่ง ฟิลด์นี้เป็นฟิลด์ที่ต้องระบุ

เนื้อหาคำขอ

ฟิลด์ entities มี movieEntity และ tvEpisodeEntity แยกออกจากกัน

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

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

{
  "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 นาที และปฏิบัติตามข้อกำหนดในการดู เช่น ดูภาพยนตร์บางส่วนหรือดูตอนจนจบตอน ดูรายละเอียดได้ในหลักเกณฑ์ฟีดวิดีโอถัดไปสำหรับนักพัฒนาแอป