ממשק API לינארי להטמעת מודעות דינמיות

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

שירות: dai.google.com

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

שיטה: זרם

בקשת HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

כותרת הבקשה

Authorization: DCLKDAI key="<api-key>"

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

גוף הבקשה

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול Stream עבור שידורים עם משׂואת רשת (beacon) בצד השרת, הקוד Stream מכיל רק את השדות stream_id ו-stream_manifest.

פתיחת המדידה

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

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

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

הבקשות שנשלחות לנקודת הקצה (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)

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

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

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

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

בקשת 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,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}

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

סמל

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