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

באמצעות Dynamic Ad Insertion API אפשר לבקש ולעקוב אחרי שידורים חיים עם הטמעת מודעות דינמיות.

שירות: dai.google.com

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

שיטה: זרם

בקשת HTTP

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

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

גוף הבקשה

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

גוף התשובה

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

Open Measurement

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

שיטה: פילוח של pod

בקשת HTTP

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

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

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

הערות שוליים

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

דוגמה

ה. ה. ה https://dai.google.com. ה. ה. ה. ה. ה. ה. ה. ה https://dai.google.com... ה. ה.דירוג. ה. . ה. ה. . ה. . ה. ה. ה. ה. ה. ה. ה. ה. .. ה. ה. . הפונקציה. ה. ה. ה. ה. ה. ה https://dai.google.com... ה. הידר. ה. ה. ש ה. ה. ה. ה. ה. ה. ה. ה. ה.

GET https://dai.google.com/ וליניארי/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so35a1ac_ts_a/1.ts?so=0&sd0dstream=100

גוף התשובה

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

שיטה: מניפסט של קבוצת צמתים (pod) ב-HLS

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

בקשת HTTP

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

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

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה הוא פלייליסט HLS עם וריאנטים מרובים.

שיטה: מניפסט של אשכול DASH

אחזור מניפסט של מודעות MPEG-DASH בשידור חי, שמוכנה לטעינה ולהפעלה בנגן וידאו של לקוח.

בקשת HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

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

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה הוא פלייליסט mpd של MPEG-DASH.

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

בקשת HTTP

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

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

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

גוף התשובה

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

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

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

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

בקשת HTTP

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

גוף התשובה

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

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

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

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

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

שיטה: metadata

נקודת הקצה של המטא-נתונים ב-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.

נתוני התגובה

מקור נתונים

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

PodMetadata

{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}

TagSegment

{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}

AdBreak

{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}

מודעה

{
  "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),
}

PodTemplateResponse

{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}

סמל

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

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Wrapper

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

אימות

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

TrackingEvent

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

Companion

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

InteractiveFile

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}