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

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

‫Engage SDK מציע REST API כדי לספק חוויה עקבית של "המשך צפייה" בפלטפורמות שאינן Android, כמו iOS ו-Roku TV. ממשק ה-API מאפשר למפתחים לעדכן את הסטטוס "המשך צפייה" עבור משתמשים שהביעו הסכמה, מפלטפורמות שאינן Android.

דרישות מוקדמות

• קודם צריך לסיים את השילוב של ה-SDK של Engage במכשיר. השלב הזה חשוב מאוד כי הוא יוצר את השיוך הנדרש בין מזהה המשתמש של 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, צריך לפעול לפי השלבים האלה.

פרסום אוסף ההמשכים

כדי לפרסם את נתוני מודעות הווידאו Discovery, צריך לשלוח בקשת 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. זה שדה חובה.

גוף הבקשה

השדה 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"
      }
    }
  ]
}

מחיקת נתוני הגילוי של הסרטון

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

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

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

איפה:

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

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

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

בדיקה

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

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