הטמעה של התכונה 'המשך צפייה' באמצעות API בארכיטקטורת REST

‫Engage SDK מציע API בארכיטקטורת REST כדי לספק חוויה עקבית של "המשך צפייה" בפלטפורמות שאינן פלטפורמת 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. אחרי שיוצרים את חשבון השירות, מקבלים שני פריטים:
    • מזהה חשבון שירות.
    • קובץ JSON עם המפתח של חשבון השירות. חשוב לשמור על הקובץ הזה מאובטח. תצטרכו אותו כדי לאמת את הלקוח ב-API בהמשך.
  5. עכשיו אפשר להשתמש ב-API בארכיטקטורת REST בחשבונות Workspace ובחשבונות Google שמשויכים אליהם. אחרי שהשינוי יופץ, תקבלו הודעה אם ה-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

המטען הייעודי (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.

במהלך הבדיקה, צריך להמתין כמה דקות עד שהשינויים יתעדכנו, ולעמוד בדרישות הצפייה, כמו צפייה בחלק מסרט או סיום צפייה בפרק. פרטים נוספים זמינים בהנחיות למפתחי אפליקציות בנושא התכונה "הצעות לצפייה".