Engage SDK מציע API בארכיטקטורת REST כדי לספק חוויה עקבית של "המשך צפייה" בפלטפורמות שאינן פלטפורמת Android, כמו iOS ו-Roku TV. ממשק ה-API מאפשר למפתחים לעדכן את הסטטוס "המשך צפייה" עבור משתמשים שהביעו הסכמה, מפלטפורמות שאינן Android.
דרישות מוקדמות
- קודם צריך לסיים את השילוב במכשיר שמבוסס על Engage SDK. השלב החשוב הזה יוצר את השיוך הנדרש בין מזהה המשתמש של Google לבין
AccountProfileשל האפליקציה. - גישה ל-API ואימות: כדי לראות ולהפעיל את ה-API בפרויקט בענן ב-Google Cloud, צריך לעבור תהליך של הוספה לרשימת ההיתרים. כל בקשות ה-API מחייבות אימות.
קבלת גישה
כדי לקבל גישה לצפייה ב-API ולהפעלה שלו במסוף Google Cloud, צריך לרשום את החשבון.
- מספר הלקוח ב-Google Workspace אמור להיות זמין. אם אין לכם חשבון, יכול להיות שתצטרכו להגדיר חשבון Google Workspace וגם חשבונות Google שבהם אתם רוצים להשתמש כדי לשלוח קריאות ל-API.
- מגדירים חשבון במסוף Google Cloud באמצעות כתובת אימייל שמשויכת ל-Google Workspace.
- יוצרים פרויקט חדש.
- יוצרים חשבון שירות לאימות API. אחרי שיוצרים את חשבון השירות, מקבלים שני פריטים:
- מזהה חשבון שירות.
- קובץ JSON עם המפתח של חשבון השירות. חשוב לשמור על הקובץ הזה מאובטח. תצטרכו אותו כדי לאמת את הלקוח ב-API בהמשך.
- עכשיו אפשר להשתמש ב-API בארכיטקטורת REST בחשבונות Workspace ובחשבונות Google שמשויכים אליהם. אחרי שהשינוי יופץ, תקבלו הודעה אם ה-API מוכן לקריאה על ידי חשבונות השירות שלכם.
- כדי להתכונן לביצוע קריאה ל-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
המטען הייעודי (payload) של הבקשה מיוצג בשדה entities. entities מייצג רשימה של ישויות תוכן, שיכולה לכלול אחד או יותר מהערכים הבאים: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity או VideoClipEntity.
זה שדה חובה.
גוף הבקשה
שדה |
סוג |
חובה |
תיאור |
ישויות |
רשימה של אובייקטים מסוג MediaEntity |
כן |
רשימה של ישויות תוכן, עד 5. רק חמשת הראשונים יישמרו והשאר יימחקו. רשימה ריקה יכולה לציין שהמשתמש סיים לצפות בכל הישויות. |
השדה entities מכיל את הערכים הנפרדים movieEntity, tvEpisodeEntity, liveStreamingVideoEntity ו-videoClipEntity.
שדה |
סוג |
תיאור |
movieEntity |
MovieEntity |
אובייקט שמייצג סרט בתוך ContinuationCluster. |
tvEpisodeEntity |
TvEpisodeEntity |
אובייקט שמייצג פרק בתוכנית טלוויזיה ב-ContinuationCluster. |
liveStreamingVideoEntity |
LiveStreamingVideoEntity |
אובייקט שמייצג וידאו בשידור חי בתוך ContinuationCluster. |
videoClipEntity |
VideoClipEntity |
אובייקט שמייצג קטע וידאו בתוך ContinuationCluster. |
כל אובייקט במערך הישויות חייב להיות אחד מסוגי MediaEntity הזמינים, כלומר MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity או VideoClipEntity, יחד עם שדות נפוצים ושדות ספציפיים לסוג.
בקטע הקוד הבא מוצג המטען הייעודי (payload) של גוף הבקשה ל-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 של clearCluster כדי להסיר את הנתונים של Engage.
כדי למחוק את נתוני אשכול ההמשך, שולחים בקשת POST ל-API של clearCluster באמצעות התחביר הבא.
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster
כאשר:
-
package_name: שם החבילה של ספק המדיה. -
accountId: המזהה הייחודי של חשבון המשתמש במערכת שלכם. הוא צריך להיות זהה ל-accountIdשמופיע בנתיב במכשיר. -
profileId: המזהה הייחודי של פרופיל המשתמש בחשבון במערכת שלכם. הוא צריך להיות זהה ל-profileId שמופיע בנתיב במכשיר.
כתובת ה-URL של החשבון בלי הפרופיל היא:
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster
המטען הייעודי (payload) של ה-API של clearCluster מכיל רק שדה אחד, reason, שמכיל DeleteReason שמציין את הסיבה להסרת הנתונים.
{
"reason": "DELETE_REASON_LOSS_OF_CONSENT"
}
בדיקה
אחרי פרסום הנתונים בהצלחה, משתמשים בחשבון בדיקה כדי לוודא שהתוכן הרצוי מופיע בשורה "המשך צפייה" בפלטפורמות היעד של Google, כמו Google TV ואפליקציות Google TV לנייד ב-Android וב-iOS.
במהלך הבדיקה, צריך להמתין כמה דקות עד שהשינויים יתעדכנו, ולעמוד בדרישות הצפייה, כמו צפייה בחלק מסרט או סיום צפייה בפרק. פרטים נוספים זמינים בהנחיות למפתחי אפליקציות בנושא התכונה "הצעות לצפייה".