Early ad break notification

שימוש ב-API של התראה מוקדמת של הפסקה למודעות

הערה: ה-API הזה עדיין בגרסת בטא. אם אתם רוצים לבקש גישה לתוכנית EABN, עליכם לפנות למנהל החשבון שלכם.

ממשק ה-API של התראה מוקדמת על הפסקה למודעה (EABN) מאפשר לכם להודיע ל-Google Ad Manager על ההפסקה הקרובה למודעה עם המטא-נתונים שלה לפני תחילת ההפסקה למודעה. אתם יכולים לשלוח בקשה להתראה עד שעה לפני ההפסקה למודעות. במדריך הזה מוסבר איך להפעיל את EABN API ולהשתמש בו, וגם איך לבקש דוגמאות ולענות להן.

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

קריאות ל-EABN API חייבות לכלול את הפרטים הבאים:

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

הערה: צריך להפעיל את ההגדרה כדי להשתמש במזהה הזה. למידע נוסף אפשר לפנות למנהל החשבון.

  • משך הזמן הצפוי של ההפסקה הבאה למודעות. משך הזמן צריך להיות קרוב ככל האפשר למשך ההפסקה למודעה בפועל.

בנוסף לשדות החובה האלה, אפשר גם לשלוח פרמטרים מותאמים אישית של טירגוט, את שם התבנית של רצף מודעות שרוצים להחיל או נתוני Cue Out של SCTE35, אם הם זמינים.

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

כדי להשתמש ב-EABN API, עליך ליצור חשבון שירות ולהוסיף את החשבון לרשת Google Ad Manager שלך.

יצירת חשבון שירות

כך יוצרים חשבון שירות לקריאה ל-EABN API: - אם יש לכם חשבון Google Cloud, תוכלו להשתמש במודול IAM כדי ליצור חשבון שירות. מידע נוסף זמין במאמר יצירה וניהול של חשבונות שירות. - אם אין לכם חשבון Google Cloud, עליכם לפעול לפי השלבים הבאים כדי ליצור חשבון דרך Google API Console:

  1. יוצרים פרויקט חדש או בוחרים פרויקט קיים.
  2. בדף Credentials, לוחצים על Manage service accounts.
  3. בדף Service accounts (חשבונות שירות), לוחצים על יצירת חשבון שירות.
  4. בדף Create Service account, מזינים את פרטי החשבון. לאחר מכן לוחצים על יצירה.

אחרי שיוצרים חשבון שירות, מעתיקים את מפתח ה-JSON של החשבון, שמשמש לאימות.

הוספה של חשבון השירות לרשת Google Ad Manager

כדי להוסיף את חשבון השירות לרשת, מבצעים את השלבים במאמר הוספת משתמש של חשבון שירות לגישה ל-API.

הפעלת ה-API

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

  • כתובת האימייל של חשבון Google Cloud
  • חשבון השירות שלך
  • קוד הרשת של רשת Google Ad Manager.

אחרי שמנהל החשבון הפעיל את ה-API, צריך לבצע את השלבים הבאים כדי להפעיל אותו:

  1. בספריית Google API, מחפשים את Google Ad Manager Video API.
  2. לוחצים על הפעלה.

הערה: אם ממשק ה-API לא מופיע בתוצאות החיפוש, צריך לפנות למנהל החשבון כדי לוודא שבחשבון הופעל DAI API.

שימוש ב-API

אפשר לשלוח קריאה ל-API של EABN באמצעות בקשות JSON/REST.

אישור

כדי לבצע קריאות מורשות ל-EABN API, צריך ליצור פרטי כניסה לחשבון שירות ב-OAuth2 באמצעות מפתח JSON מחשבון השירות וההיקף https://www.googleapis.com/auth/video-ads. למידע נוסף, ראו שימוש ב-OAuth 2.0 לאפליקציות משרת לשרת.

צריך לכלול את אסימון ההרשאה שמתקבל ככותרת אימות בכל קריאה ל-EABN API.

שליחת התראה על הפסקה מוקדמת למודעה

כדי לשלוח התראה על הפסקה מוקדמת למודעה, צריך לשלוח בקשת POST לאחת משלוש כתובות ה-URL החוקיות של EABN, בהתאם לאופן שבו אתם מעדיפים לציין את השידור החי. בקטעים הבאים מוסברים ההבדלים בין כתובות ה-URL ודוגמאות לבקשות ולתגובות.

כתובות URL

יש שלוש כתובות URL חוקיות להתראה מוקדמת על הפסקות למודעות. אפשר להשתמש בכל שלושת הסוגים כדי ליצור הפסקה למודעה (POST) או לקבל את רשימת ההפסקות למודעות (GET).

כדי להשתמש במפתח הנכס של שידור חי, משתמשים באפשרויות הבאות:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

כדי להשתמש במפתח נכס מותאם אישית של שידור חי, משתמשים באפשרויות הבאות:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

כדי להשתמש בגישה של Content ID ושל Content ID, משתמשים ב:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

לגבי כל הפרמטרים:

  • network_code מייצג את קוד הרשת של רשת Google Ad Manager.
  • asset_key מייצג את מַפתח הנכס שמוצג בדף הפרטים של השידור החי.
  • custom_asset_key מייצג את מַפתח הנכס המותאם אישית של השידור החי.
  • content_source_id מייצג את המזהה של מקור תוכן ב-Google Ad Manager.
  • content_id מייצג את המזהה של קטע תוכן ב-Google Ad Manager.

הערה: הצמד content_source_id/content_id שצוין צריך להיות משויך לשידור חי ב-Google Ad Manager.

גוף הבקשה – משמש רק ליצירת הפסקות למודעות (POST)

אובייקט

expectedDuration

 חובה משך ההפסקה למודעה הזו, באמצעות פורמט משך הזמן הסטנדרטי של Google (xx.xxxs, כאשר xx.xxx הוא מספר השניות)

customParams

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

=

וגם מצטרפים

&


.לדוגמה:

key=value&key2=value2,value3


מידע נוסף על טירגוט זמין במאמר הוספת פרמטרים של טירגוט לשידור הנתונים.

podTemplateName

 אופציונלי שם התבנית של רצף המודעות

scte35CueOut

 אופציונלי נתונים בקידוד Base-64 מיציאת scte35. יכול לכלול את

splice_insert()

או

time_signal()

הפקודה.
דוגמאות:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

דוגמאות לבקשות

יצירת הפסקה למודעה
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
גוף התשובה

גוף התגובה מכיל את כל הפרמטרים שנשלחו באובייקט adBreak, וגם שדה name נוסף, שמכיל את המזהה הרגיל של כל ההפסקה למודעה שנוצרה. השדה הזה מוחזר בפורמט הבא:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
דוגמה לתגובה
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
רשימת ההפסקות למודעות שהוקצו
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
גוף התשובה

גוף התגובה מכיל את ההפסקות למודעות עם שדה breakState נוסף לכל הפסקה למודעה שמוקצית לשידור. השדה breakState תומך בערכים הבאים:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
דוגמה לתגובה
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}