ادغام کردن ادامه تماشا بااستفاده از REST API

Engage SDK یک REST API ارائه می‌دهد تا تجربه تماشای مداوم و ثابتی را در پلتفرم‌های غیرAndroid مانند iOS و Roku TV فراهم کند. این میانای برنامه‌سازی کاربردی به توسعه‌دهندگان اجازه می‌دهد وضعیت «ادامه تماشا» را برای کاربران موافقت‌کرده از پلاتفرم‌های غیرAndroid به‌روز کنند.

پیش‌نیازها

  • ابتدا باید یکپارچه‌سازی مبتنی بر Engage SDK درون‌دستگاهی را تکمیل کنید. این مرحله حیاتی ارتباط لازم را بین شناسه کاربر Google و AccountProfile برنامه‌تان برقرار می‌کند.
  • دسترسی و اصالت‌سنجی میانای برنامه‌سازی کاربردی: برای مشاهده و فعال کردن میانای برنامه‌سازی کاربردی در «پروژه Google Cloud»، باید فرایند فهرست مجاز را طی کنید. همه درخواست‌های میانای برنامه‌سازی کاربردی به اصالت‌سنجی نیاز دارند.

دسترسی یافتن

برای دسترسی به مشاهده و فعال کردن میانای برنامه‌سازی کاربردی در «کنسول Google Cloud»، حسابتان باید ثبت‌نام شده باشد.

  1. شناسه مشتری Google Workspace باید دردسترس باشد. اگر دردسترس نیست، ممکن است لازم باشد Google Workspace و همچنین هر «حساب Google» دیگری را که می‌خواهید برای فراخوانی API استفاده کنید راه‌اندازی کنید.
  2. بااستفاده از ایمیل منسوب به Google Workspace، حسابی در «کنسول Google Cloud» راه‌اندازی کنید.
  3. پروژه جدیدی ایجاد کنید.
  4. حساب سرویسی برای «اصالت‌سنجی API» ایجاد کنید. پس‌از ایجاد حساب سرویس، دو مورد خواهید داشت:
    • شناسه حساب سرویس.
    • فایل JSON با کلید حساب سرویس شما. این فایل را ایمن نگه‌دارید. بعداً برای اصالت‌سنجی کردن کارخواهتان در API به آن نیاز خواهید داشت.
  5. اکنون Workspace و «حساب‌های Google» مرتبط می‌توانند از REST API استفاده کنند. وقتی تغییر منتشر شد، به شما اطلاع داده می‌شود که API برای فراخوانی توسط حساب‌های سرویس شما آماده است یا نه.
  6. این مراحل را برای آماده شدن برای برقراری تماس API واگذارشده دنبال کنید.

خوشه ادامه را منتشر کنید

برای انتشار داده‌های Engage، درخواست POST را بااستفاده از نحو زیر برای publishContinuationCluster API اجرا کنید.

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

مکان:

  • ‫package_name: نام بسته ارائه‌دهنده رسانه
  • accountId: شناسه یکتای حساب کاربر در سیستم شما. باید با accountId استفاده‌شده در مسیر درون‌دستگاهی مطابقت داشته باشد.
  • profileId: شناسه یکتا برای نمایه کاربر در حساب موجود در سیستم شما. باید با profileId استفاده‌شده در مسیر درون‌دستگاهی مطابقت داشته باشد.

نشانی وب حساب بدون نمایه:

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

بار مفید درخواست در فیلد entities نشان داده می‌شود. entities نشان‌دهنده فهرستی از نهادهای محتوا است که می‌تواند شامل یک یا چند مورد از موارد زیر باشد: MovieEntity، TVEpisodeEntity، LiveStreamingVideoEntity یا VideoClipEntity. این فیلد الزامی است.

متن درخواست

فیلد

تایپ کردن

الزامی

شرح

نهادها

فهرست اشیاء MediaEntity

بله

فهرست نهادهای محتوا با حداکثر ۵ مورد. فقط پنج مورد برتر حفظ می‌شوند و بقیه حذف می‌شوند. فهرست خالی مجاز است تا نشان دهد کاربر تماشای همه نهادها را به‌پایان رسانده است.

فیلد entities شامل movieEntity، tvEpisodeEntity، liveStreamingVideoEntity، و videoClipEntity است.

فیلد

تایپ کردن

شرح

movieEntity

MovieEntity

شیء نشان‌دهنده فیلم در ContinuationCluster.

tvEpisodeEntity

TvEpisodeEntity

شیء نشان‌دهنده قسمت تلویزیونی در ContinuationCluster.

liveStreamingVideoEntity

LiveStreamingVideoEntity

An object representing a live streaming video within the ContinuationCluster.

videoClipEntity

VideoClipEntity

شیء نشان‌دهنده کلیپ ویدیویی در ContinuationCluster.

هر شیء در آرایه نهادها باید یکی از انواع MediaEntity دردسترس باشد، یعنی MovieEntity، TvEpisodeEntity، LiveStreamingVideoEntity، یا VideoClipEntity، به‌همراه فیلدهای رایج و مختص نوع.

تکه‌کد زیر بار داده بدنه درخواست را برای publishContinuationCluster API نشان می‌دهد.

{
  "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

برای برداشتن داده‌های Engage، از میانای برنامه‌سازی کاربردی clearCluster استفاده کنید.

برای حذف داده‌های خوشه ادامه‌دار، درخواست POST را بااستفاده از نحو زیر به clearCluster API ارسال کنید.

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

مکان:

  • ‫package_name: نام بسته ارائه‌دهنده رسانه.
  • accountId: شناسه یکتای حساب کاربر در سیستم شما. باید با accountId استفاده‌شده در مسیر درون‌دستگاهی مطابقت داشته باشد.
  • profileId: شناسه یکتا برای نمایه کاربر در حساب موجود در سیستم شما. باید با profileId استفاده‌شده در مسیر درون‌دستگاهی مطابقت داشته باشد.

نشانی وب حساب بدون نمایه:

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

بار داده برای clearCluster API فقط حاوی یک فیلد، reason، است که حاوی DeleteReason است که دلیل برداشتن داده‌ها را مشخص می‌کند.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

آزمایش

پس‌از پست کردن موفقیت‌آمیز داده‌ها، از حساب آزمایشی کاربر استفاده کنید تا تأیید کنید که محتوای موردانتظار در ردیف «ادامه تماشا» در سطوح هدف Google مانند Google TV و برنامه‌های تلفن همراه Google TV برای Android و iOS ظاهر می‌شود.

در آزمایش، تأخیر انتشار معقول چند دقیقه‌ای را درنظر بگیرید و الزامات تماشا را رعایت کنید، مانند تماشای بخشی از فیلم یا تمام کردن یک قسمت. برای جزئیات، به دستورالعمل‌های «بعدی برای تماشا» برای توسعه‌دهندگان نرم‌افزار مراجعه کنید.