ادغام قابلیت ادامه تماشا با استفاده از REST API

مسیر_کتاب: /distribute/other-docs/_book.yaml مسیر_پروژه: /distribute/other-docs/_project.yaml

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

پیش‌نیازها

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

دسترسی پیدا کنید

برای دسترسی به مشاهده و فعال کردن API در کنسول Google Cloud خود، باید حساب کاربری خود را ثبت کنید.

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

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

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

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

بار داده‌ای (payload) درخواست در فیلد entities نمایش داده می‌شود. entities لیستی از موجودیت‌های محتوا را نشان می‌دهند که می‌توانند MovieEntity یا TVEpisodeEntity باشند. این یک فیلد اجباری است.

درخواست بدنه

entities فیلد شامل movieEntity و tvEpisodeEntity به صورت جداگانه هستند.

هر شیء در آرایه entityها باید یکی از انواع 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"
      }
    }
  ]
}

داده‌های کشف ویدیو را حذف کنید

از API clearClusters برای حذف داده‌های مربوط به کشف ویدیو استفاده کنید.

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

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

کجا:

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

بار مفید (payload) مربوط به API مربوط به clearClusters فقط شامل یک فیلد به reason است که شامل یک DeleteReason است که دلیل حذف داده‌ها را مشخص می‌کند.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

آزمایش

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

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