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

‫Dynamic Ad Insertion API מאפשר לכם לבקש שידורים לינאריים (בשידור חי) של DAI ולעקוב אחריהם.

שירות: dai.google.com

כל כתובות ה-URI הן יחסיות ל-https://dai.google.com

שיטה: סטרימינג

בקשת HTTP

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

Request header

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

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

גוף הבקשה

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל Stream חדש. בסטרימינג של נתוני beacon בצד השרת, Stream מכיל רק את השדות stream_id ו-stream_manifest.

מדידה פתוחה

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

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

אחרי שנתקלים במזהה של מדיה פרסומית במהלך ההפעלה, צריך לשלוח מיד בקשה באמצעות media_verification_url שהתקבל מנקודת הקצה stream. הבקשות האלה לא נדרשות לסטרימינג של נתוני שימוש (beaconing) בצד השרת, שבו השרת מתחיל את אימות המדיה.

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

נקודת הקצה של המטא-נתונים בכתובת metadata_url מחזירה מידע שמשמש ליצירת ממשק משתמש של מודעה. נקודת הקצה של המטא-נתונים לא זמינה לסטרימינג של אותות (beacons) בצד השרת, שבו השרת אחראי להפעלת אימות של מדיה פרסומית.

בקשת 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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}

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