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

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

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

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, LiveStreamingVideoEntity หรือ VideoClipEntity อย่างน้อย 1 รายการ ฟิลด์นี้เป็นฟิลด์ที่ต้องระบุ

เนื้อหาคำขอ

ฟิลด์

ประเภท

ต้องระบุ

คำอธิบาย

entities

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

ใช่

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

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

ฟิลด์

ประเภท

คำอธิบาย

movieEntity

MovieEntity

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

tvEpisodeEntity

TvEpisodeEntity

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

liveStreamingVideoEntity

LiveStreamingVideoEntity

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

videoClipEntity

VideoClipEntity

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

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

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

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/movie_entity_uri_for_android",
          "platforms": [
            "PLATFORM_ANDROID_TV",
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/movie_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/movie1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Movie 1 HD poster"
          },
          {
            "url": "http://www.example.com/movie1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Movie 1 SD poster"
          }
        ],
        "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": [
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
          "platforms": [
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_tv",
          "platforms": [
            "PLATFORM_ANDROID_TV"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/episode1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Episode 1 HD poster"
          },
          {
            "url": "http://www.example.com/episode1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Episode 1 SD poster"
          }
        ],
        "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"
      }
    },
    {
      "liveStreamingVideoEntity": {
        "name": "Live Sports Championship",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 1800000,
        "duration_millis": 7200000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/live_stream_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Live Sports Championship Cover Image"
          }
        ],
        "start_time_epoch_millis": 1780976484000,
        "broadcaster": "Global Sports Network",
        "broadcaster_icon": {
          "url": "https://www.example.com/gsports.jpg",
          "width": 512,
          "height": 512,
          "accessibility_text": "Global Sports Network Logo"
        }
      }
    },
    {
      "videoClipEntity": {
        "name": "How to Brew the Perfect Espresso",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 120000,
        "duration_millis": 600000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/video_clip_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Espresso Tutorial Cover Image"
          }
        ],
        "created_time_epoch_millis": 1780900000000,
        "creator": "Coffee Enthusiast John",
        "creator_image": {
          "url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
          "width": 256,
          "height": 256,
          "accessibility_text": "John's Avatar"
        }
      }
    }
  ]
}

ลบข้อมูล Engage

ใช้ API clearClusters เพื่อนำข้อมูล Engage ออก

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

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

สถานที่:

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

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

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

การทดสอบ

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

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