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

כתובת ה-URL של החשבון ללא פרופיל היא:

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

המטען הייעודי (payload) של הבקשה מיוצג בשדה entities. ‫entities מייצג רשימה של ישויות תוכן, שיכולות להיות MovieEntity או TVEpisodeEntity. זה שדה חובה.

גוף הבקשה

השדה entities מכיל את הערכים movieEntity ו-tvEpisodeEntity.

כל אובייקט במערך הישויות חייב להיות אחד מסוגי MediaEntity הזמינים, כלומר MovieEntity ו-TvEpisodeEntity, יחד עם שדות משותפים ושדות ספציפיים לסוג.

בקטע הקוד הבא מוצג מטען ייעודי (payload) של גוף הבקשה עבור publishContinuationCluster API.

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

מחיקת הנתונים של Engage

משתמשים ב-clearClusters API כדי להסיר את נתוני Engage.

כדי למחוק את נתוני אשכול ההמשכיות, שולחים בקשת POST אל clearClusters API באמצעות התחביר הבא.

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

כאשר:

• ‫package_name: שם החבילה של ספק המדיה.
• ‫accountId: המזהה הייחודי של חשבון המשתמש במערכת שלכם. הוא צריך להיות זהה ל-accountId שמופיע בנתיב במכשיר.
• ‫profileId: המזהה הייחודי של הפרופיל של המשתמש בחשבון במערכת שלכם. המזהה צריך להיות זהה למזהה הפרופיל שמשמש בנתיב במכשיר.

המטען הייעודי (payload) של clearClusters API מכיל רק שדה אחד, reason, שמכיל DeleteReason שמציין את הסיבה להסרת הנתונים.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

בדיקה

אחרי פרסום הנתונים בהצלחה, משתמשים בחשבון בדיקה כדי לוודא שהתוכן הרצוי מופיע בשורה 'המשך צפייה' בפלטפורמות היעד של Google, כמו Google TV ואפליקציות Google TV לנייד ב-Android וב-iOS.

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