ממשק API להצגת מודעות דינמיות של הטמעת מודעות דינמיות (DAI)

ה-API של הטמעת מודעות דינמיות (DAI) מאפשר לשלוח בקשות לשידורים חיים של DAI ולעקוב אחריהן.

שירות: dai.google.com

כל מזהי ה-URI הם יחסיים ל-https://dai.google.com.

שיטה: זרם

שיטות
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

רושם רצף מודעות של DAI DAI להצגת סשן של שידור חי.

בקשת HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

פרמטרים של נתיב

פרמטרים
network_code string

קוד רשת Google Ad Manager של בעל התוכן הדיגיטלי.

custom_asset_key string

המזהה המותאם אישית שמשויך לאירוע הזה ב-Google Ad Manager.

גוף הבקשה

גוף הבקשה הוא מסוג application/x-www-form-urlencoded ומכיל את הקוד את הפרמטרים הבאים:

פרמטרים
פרמטרים של טירגוט ב-DFP אופציונלי פרמטרים נוספים של טירגוט.
שינוי פרמטרים של מקור נתונים אופציונלי שינוי ערכי ברירת המחדל של הפרמטר ליצירת שידור.
אימות HMAC אופציונלי אימות באמצעות אסימון מבוסס HMAC.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל אובייקט Stream חדש.

פתיחת המדידה

ה-DAI API מכיל מידע לצורך אימות מדידה פתוחה Verifications. השדה הזה מכיל לפחות שדה אחד רכיבי Verification שמפרטים את המשאבים והמטא-נתונים שנדרשים להפעלה קוד מדידה של צד שלישי כדי לאמת את הפעלת הקריאייטיב. רק יש תמיכה ב-JavaScriptResource. מידע נוסף זמין במאמר IAB Tech Lab מפרט VAST 4.1.

שיטה: מקטע של Pod

שיטות
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

יוצר מקור נתונים של DAI למזהה האירוע הנתון.

בקשת HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

פרמטרים של נתיב

פרמטרים
network_code string

קוד רשת Google Ad Manager של בעל התוכן הדיגיטלי.

custom_asset_key string

המזהה המותאם אישית שמשויך לאירוע הזה ב-Google Ad Manager.

pod_id integer

המזהה המספרי של ההפסקה הנוכחית למודעות. המזהים של רצף המודעות הם מוקצה באופן מצטבר לכל אירוע, החל מ-1.
profile_name string

שם של הבקשות פרופיל קידוד DAI ב-Google Ad Manager. פרופיל הקידוד חייב להיות אחד מפרופילי הקידוד שהוגדרו עבור אל האירוע שנבחר.

segment_number integer

האינדקס של הקטע המבוקש בתוך רצף המודעות הנוכחי, החל מאפס.
segment_format string

סיומת הקובץ שמשויכת לפורמט הפלח המבוקש. התוספים הקבילים הם: ts, mp4, vtt, aac, ac3 או eac3.

פרמטרים של שאילתה

פרמטרים
stream_id חובה string

מזהה מקור הנתונים של הסשן של המשתמש הנוכחי. הערך הזה מוחזר על ידי בקשה שהופעלה בהצלחה לנקודת הקצה (endpoint) stream.
sd required1 integer

משך הזמן של הפלח המבוקש, באלפיות השנייה.
so אופציונלי

ההיסט של הקטע המבוקש בתוך רצף המודעות, באלפיות השנייה. אם משמיטים את הפרמטר so, הוא יחושב לפי הכפלה של משך הקטע במספר הפלח.
pd חובה2 integer

משך הזמן של רצף המודעות, באלפיות השנייה.
auth-token חובה string

כתובת URL חתומה בקידודי תווים שמתאימים לכתובות URL אסימון HMAC לרצף המודעות הנוכחי.
last אופציונלי boolean

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

SCTE-35signal בקידוד Base64 בשביל ההפסקה למודעות הזו.
cust_params אופציונלי string

קבוצה של צמדי מפתח/ערך שמשמשים לטירגוט הקמפיין ב-Ad Manager. האלה חייבים להיות מיוצגים כמחרוזת שאילתה עם קידוד כתובת URL.

דוגמה:
פרמטרים
  • קטע = sports
  • דף = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

הערות שוליים

  1. sd לא נדרש עבור מקטעי אתחול. ↩
  2. לא נדרש שימוש בפרמטר pd באירועים עם מודעות ללא משך זמן ההפסקות הופעלו. ↩

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יהיה קטע בשידור שניתן להפעיל, שתואם ל- הפורמט והפרמטרים שצוינו בבקשה.

שיטה: תבנית תקופת רצף DASH

שיטות
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

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

בקשת HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

פרמטרים של נתיב

פרמטרים
network_code string

קוד רשת Google Ad Manager של בעל התוכן הדיגיטלי.

custom_asset_key string

המזהה המותאם אישית שמשויך לאירוע הזה ב-Google Ad Manager.

פרמטרים של שאילתה

פרמטרים
stream_id חובה string

מזהה מקור הנתונים של הסשן של המשתמש הנוכחי. הערך הזה מוחזר על ידי בקשה שהופעלה בהצלחה לנקודת הקצה (endpoint) stream.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול אובייקט PodTemplateResponse.

שיטה: אימות מדיה

לאחר שנתקלת במזהה מדיה של מודעה במהלך ההפעלה, צור מיד בקשה באמצעות ה-media_verification_url שקיבלתם מה-stream נקודת הקצה, למעלה. הבקשות האלה לא נחוצות ליצירת חיישנים בצד השרת ב-streams, שבהם השרת יוזם אימות מדיה.

הבקשות שנשלחות לנקודת הקצה (endpoint) media verification הן אידמפוטנטיות.

שיטות
media verification GET /{media_verification_url}/{ad_media_id}

שליחת התראה ל-API על אירוע אימות מדיה.

בקשת HTTP

GET https://{media-verification-url}/{ad-media-id}

גוף התשובה

media verification מחזירה את התשובות הבאות:

  • HTTP/1.1 204 No Content אם אימות המדיה יצליח וכל הפינגים נשלח.
  • HTTP/1.1 404 Not Found אם הבקשה לא יכולה לאמת את המדיה בגלל פורמט שגוי של כתובת אתר או תאריך תפוגה.
  • HTTP/1.1 404 Not Found אם התקבלה בקשת אימות קודמת למזהה הזה הצליחה.
  • HTTP/1.1 409 Conflict אם בקשה אחרת כבר שולחת פינגים לכתובת הזו בזמן האימון.

מזהי מדיה של מודעות

מזהי מדיה של מודעות יקודדו במסלול נפרד של מטא-נתונים – מתוזמן מטא-נתונים עבור קובצי HLS בסטרימינג, או emsg לקובצי mp4. מזהי מדיה של מודעות יתחיל תמיד במחרוזת google_.

יש לצרף למודעה את כל תוכן הטקסט של רשומת המטא-נתונים לכתובת URL לאימות לפני שליחה של כל בקשה לאימות מודעה.

שיטה: מטא-נתונים

נקודת הקצה של המטא-נתונים ב-metadata_url מחזירה מידע שמשמש ליצירת מודעה ממשק משתמש. נקודת הקצה של המטא-נתונים לא זמינה בשידורים של איתות Bluetooth בצד השרת, שבו השרת אחראי להתחיל את תהליך האימות של מדיה של מודעה.

שיטות
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

אחזור של פרטי מטא-נתונים של מודעות.

בקשת HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, התשובה תחזיר מופע של PodMetadata

ניתוח מטא-נתונים

למטא-נתונים יש שלושה קטעים נפרדים: tags, ads ומודעה breaks. הרשומה של הנתונים הוא הקטע tags. לאחר מכן, לבצע איטרציה דרך התגים ומוצאים את הרשומה הראשונה ששמה הוא קידומת של מזהה מדיה של מודעה שנמצא בזרם הווידאו. לדוגמה, יכול להיות מזהה מדיה של מודעה שנראה כך:

google_1234567890

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

נתוני תגובה

מקור נתונים

עדכוני התוכן משמשים לעיבוד רשימת משאבים לשידור חדש שנוצר ב- בפורמט JSON.
ייצוג JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
שדות
stream_id string

מזהה מקור הנתונים ב-GAM.
media_verification_url string

כתובת ה-URL לאימות מדיה שמשמשת כנקודת קצה בסיסית למעקב אחר אירועי הפעלה.
metadata_url string

כתובת URL של מטא-נתונים שמשמשת לבדיקת מידע תקופתי לגבי אירועים קרובים של מודעות בסטרימינג.
session_update_url string

כתובת ה-URL לעדכון של הסשן משמשת לעדכון הפרמטרים של הטירגוט של מקור הנתונים הזה. הערכים המקוריים של הפרמטרים של הטירגוט מתועדים במהלך הבקשה הראשונית ליצירה של מקור הנתונים.
heartbeat_url string

כתובת ה-URL של פעימות הלב, שמשמשת לשמירה על השידור החי בצד השרת, צריך לשלוח לו פינג כל {PollingFrequency} שניות. השדה הזה מאוכלס לשידורים של איתות Bluetooth בצד השרת.
polling_frequency number

תדירות הדגימה, בשניות, כשמבקשים מטא-נתונים_url או פעימה_url.
pod_manifest_url string

התבנית של כתובת ה-URL של מניפסט ה-Pod משמשת ליצירת כתובת ה-URL לאחזור מניפסט Pod של שידור. שתואם לכתובת ה-URL של הפלייליסט מרובה המשתנים ב-HLS או ל-MPD ב-DASH. השדה הזה מאוכלס באירועי שידור חי מסוג POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

פורמט מניפסט הוא הפורמט של המניפסט שאוחזר מ-pod_manifest_url, מקף או hls.

PodMetadata

ה-PodMetadata מכיל פרטי מטא-נתונים על מודעות, הפסקות למודעות ותגים של מזהה מדיה.
ייצוג JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
שדות
tags map[string, object(TagSegment)]

מפה של קטעי התג שנוספו לאינדקס לפי קידומת התג.
ads map[string, object(Ad)]

מפה של המודעות שנוספו לאינדקס לפי מזהה המודעה.
ad_breaks map[string, object(AdBreak)]

מפה של הפסקות למודעות שנוספו לאינדקס לפי מזהה ההפסקה למודעה.

TagSegment

TagSegment מכיל הפניה למודעה, הפסקה למודעה וסוג האירוע. TagSegment עם type="progress" לא לבצע פינג למדיה של המודעה נקודת הקצה לאימות.
ייצוג JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
שדות
ad string

המזהה של המודעה של התג הזה.
ad_break_id string

המזהה של ההפסקה למודעה בתג הזה.
type string

סוג האירוע של התג הזה.

AdBreak

AdBreak מתאר הפסקה אחת למודעה בזרם. הוא מכיל את משך הזמן, סוג (mid/pre/post) ואת מספר המודעות.
ייצוג JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
שדות
type string

סוגי ההפסקות החוקיות: לפני, באמצע ופוסט.
duration number

משך הזמן הכולל להצגת המודעה בהפסקה הזו למודעות, בשניות.
expected_duration number

משך הזמן הצפוי של ההפסקה למודעות (בשניות), כולל כל המודעות וכל תוכן אחר.
ads number

מספר המודעות בהפסקה למודעה.
מודעה שמתארת מודעה בזרם.
ייצוג JSON
{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
שדות
ad_break_id string

המזהה של ההפסקה למודעה הזו.
position number

המיקום של המודעה הזו בהפסקה למודעה, החל מ-1.
duration number

משך המודעה, בשניות.
title string

כותרת אופציונלית של המודעה.
description string

תיאור אופציונלי של המודעה.
advertiser string

מזהה מפרסם אופציונלי.
ad_system string

מערכת מודעות אופציונלית.
ad_id string

מזהה מודעה אופציונלי.
creative_id string

מזהה קריאייטיב אופציונלי.
creative_ad_id string

מזהה אופציונלי של מודעת קריאייטיב.
deal_id string

מזהה עסקה אופציונלי.
clickthrough_url string

כתובת URL אופציונלית לקליקים.
click_tracking_urls string

כתובות URL אופציונליות למעקב אחר קליקים.
verifications [object(Verification)]

רשומות אופציונליות של אימות מדידה פתוחה, שבהן מפורטות המשאבים ואת המטא-נתונים הנדרשים להפעלת קוד מדידה של צד שלישי לצורך אימות הפעלת הקריאייטיב.
slate boolean

ערך בוליאני אופציונלי שמציין שהרשומה הנוכחית היא צפחה.
icons [object(Icon)]

רשימת סמלים (אם הם ריקים).
wrappers [object(Wrapper)]

רשימה של Wrappers, אם היא ריקה.
universal_ad_id object(UniversalAdID)

מזהה מודעה אוניברסלי אופציונלי.
extensions string

רשימה אופציונלית של כל <תוסף> צמתים ב-VAST.
companions [object(Companion)]

מודעות נלוות אופציונליות שניתן להציג יחד עם מודעה זו.
interactive_file object(InteractiveFile)

קריאייטיב אינטראקטיבי (SIMID) אופציונלי שצריך להציג במהלך הפעלת המודעה.

PodTemplateResponse

PodTemplateResponse מייצג את המטען הייעודי (payload) של JSON שהוחזר ל-VTP עבור חיבור Pod.
ייצוג JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
שדות
dash_period_template string

DashPeriodTemplate הוא תבנית ה-XML של התקופה שצריך למלא בנתונים מתאימים לפני יצירת החיבור.
segment_duration_ms int64

segmentDurationMS הוא משך הזמן של מקטעי התקופה באלפיות השנייה.

סמל

הסמל מכיל מידע על סמל VAST.
ייצוג JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}
שדות
click_data object(ClickData)

creative_type string

click_fallback_images [object(FallbackImage)]

height int32

width int32

resource string

type string

x_position string

y_position string

program string

alt_text string

ClickData

ClickData מכיל מידע על לחיצה על סמל.
ייצוג JSON
{
  "url": string,
}
שדות
url string

FallbackImage

תמונת FallbackImage מכילה מידע על תמונה חלופית מסוג VAST.
ייצוג JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
שדות
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

wrapper מכיל מידע על מודעת wrapper. היא לא כוללת מזהה עסקה, אם הוא לא קיים.
ייצוג JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
שדות
system string

מזהה מערכת המודעות.
ad_id string

מזהה המודעה שמשמש את מודעת ה-wrapper.
creative_id string

מזהה הקריאייטיב שמשמש למודעת ה-wrapper.
creative_ad_id string

מזהה המודעה של הקריאייטיב שמשמש למודעת ה-wrapper.
deal_id string

מזהה עסקה אופציונלי למודעת wrapper.

אימות

האימות מכיל מידע עבור מדידה פתוחה, שמאפשר מדידת הניראות והאימות על ידי צד שלישי. בשלב זה, יש תמיכה רק במשאבי JavaScript. פרטים נוספים זמינים בכתובת https://iabtechlab.com/standards/open-measurement-sdk/
ייצוג JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
שדות
vendor string

ספק האימות.
java_script_resources [object(JavaScriptResource)]

רשימה של משאבי JavaScript לאימות.
tracking_events [object(TrackingEvent)]

רשימה של אירועי מעקב לצורך אימות.
parameters string

מחרוזת אטומה שמועברת לקוד אימות מסוג Bootstrap.

JavaScriptResource

JavaScriptResource מכיל מידע לאימות באמצעות JavaScript.
ייצוג JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
שדות
script_url string

URI למטען ייעודי (payload) של JavaScript.
api_framework string

APIFramework הוא השם של מסגרת הסרטון שמבצעת את בקוד האימות.
browser_optional boolean

האם ניתן להריץ את הסקריפט הזה מחוץ בדפדפן.

TrackingEvent

מעקב אחר אירוע מכיל כתובות URL שהלקוח צריך לשלוח להן פינג במקרים מסוימים במצבים מסוימים.
ייצוג JSON
{
  "event": string,
  "uri": string,
}
שדות
event string

הסוג של אירוע המעקב.
uri string

אירוע המעקב שצריך לשלוח אליו פינג.

UniversalAdID

UniversalAdID משמש כדי לספק מזהה קריאייטיב ייחודי שמנוהלים בכל מערכות המודעות.
ייצוג JSON
{
  "id_value": string,
  "id_registry": string,
}
שדות
id_value string

מזהה המודעה האוניברסלי של הקריאייטיב שנבחר למודעה.
id_registry string

מחרוזת שמשמשת לזיהוי כתובת ה-URL של אתר המרשם שבו מזהה המודעה האוניברסלי של הקריאייטיב שנבחר מופיע בקטלוג.

Companion

המודעה הנלווית מכילה מידע של מודעות נלוות שניתן להציג יחד עם המודעה.
ייצוג JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
שדות
click_data object(ClickData)

נתוני הקליקים של המודעה הנלווית הזו.
creative_type string

המאפיין CreativeType ב<StaticResource> צומת ב-VAST אם זוהי מודעת נלווית מסוג סטטי.
height int32

הגובה בפיקסלים של המודעה הנלווית הזו.
width int32

הרוחב בפיקסלים של המודעה הנלווית הזו.
resource string

למודעות נלוות סטטיות ו-iframe, זו תהיה כתובת ה-URL לטעינה מוצגת. עבור מודעות נלוות של HTML, זה יהיה קטע ה-HTML שאמור להיות תוצג כמודעה נלווית.
type string

סוג המודעה הנלווית הזו. היא יכולה להיות סטטית, iframe או HTML.
ad_slot_id string

מזהה המיקום של המודעה הנלווית.
api_framework string

מסגרת ה-API של המודעה הנלווית הזו.
tracking_events [object(TrackingEvent)]

רשימה של אירועי מעקב עבור המודעה הנלווית הזו.

InteractiveFile

InteractiveFile מכיל מידע של קריאייטיב אינטראקטיבי (כמו SIMID) שאמורות להיות מוצגות במהלך הפעלת המודעה.
ייצוג JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
שדות
resource string

כתובת ה-URL של הקריאייטיב האינטראקטיבי.
type string

סוג ה-MIME של הקובץ שסופק כמשאב.
variable_duration boolean

הקריאייטיב הזה עשוי לדרוש את הארכת משך הזמן.
ad_parameters string

הערך של הפרמטר <AdParameters> צומת ב-VAST.