Engage SDK یک REST API ارائه میدهد تا تجربه تماشای مداوم و ثابتی را در پلتفرمهای غیرAndroid مانند iOS و Roku TV فراهم کند. این میانای برنامهسازی کاربردی به توسعهدهندگان اجازه میدهد وضعیت «ادامه تماشا» را برای کاربران موافقتکرده از پلاتفرمهای غیرAndroid بهروز کنند.
پیشنیازها
- ابتدا باید یکپارچهسازی مبتنی بر Engage SDK دروندستگاهی را تکمیل کنید. این مرحله حیاتی ارتباط لازم را بین شناسه کاربر Google و
AccountProfileبرنامهتان برقرار میکند. - دسترسی و اصالتسنجی میانای برنامهسازی کاربردی: برای مشاهده و فعال کردن میانای برنامهسازی کاربردی در «پروژه Google Cloud»، باید فرایند فهرست مجاز را طی کنید. همه درخواستهای میانای برنامهسازی کاربردی به اصالتسنجی نیاز دارند.
دسترسی یافتن
برای دسترسی به مشاهده و فعال کردن میانای برنامهسازی کاربردی در «کنسول Google Cloud»، حسابتان باید ثبتنام شده باشد.
- شناسه مشتری Google Workspace باید دردسترس باشد. اگر دردسترس نیست، ممکن است لازم باشد Google Workspace و همچنین هر «حساب Google» دیگری را که میخواهید برای فراخوانی API استفاده کنید راهاندازی کنید.
- بااستفاده از ایمیل منسوب به Google Workspace، حسابی در «کنسول Google Cloud» راهاندازی کنید.
- پروژه جدیدی ایجاد کنید.
- حساب سرویسی برای «اصالتسنجی API» ایجاد کنید. پساز ایجاد حساب سرویس، دو مورد خواهید داشت:
- شناسه حساب سرویس.
- فایل JSON با کلید حساب سرویس شما. این فایل را ایمن نگهدارید. بعداً برای اصالتسنجی کردن کارخواهتان در API به آن نیاز خواهید داشت.
- اکنون Workspace و «حسابهای Google» مرتبط میتوانند از REST API استفاده کنند. وقتی تغییر منتشر شد، به شما اطلاع داده میشود که API برای فراخوانی توسط حسابهای سرویس شما آماده است یا نه.
- این مراحل را برای آماده شدن برای برقراری تماس 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 ظاهر میشود.
در آزمایش، تأخیر انتشار معقول چند دقیقهای را درنظر بگیرید و الزامات تماشا را رعایت کنید، مانند تماشای بخشی از فیلم یا تمام کردن یک قسمت. برای جزئیات، به دستورالعملهای «بعدی برای تماشا» برای توسعهدهندگان نرمافزار مراجعه کنید.