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

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

שירות: dai.google.com

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

שיטה: stream

בקשת 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

ממשק ה-DAI API מכיל מידע לאימות של 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 באירועים שבהם מופעלות הפסקות למודעות ללא משך זמן. ↩

דוגמה

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

גוף התשובה

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

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

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

בקשת HTTP

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}.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.

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

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

AdpodTimingMetadataResponse

{
  "status": string,
  "ads": [object(AdRendering)],
  "slate": object(SlateRendering),
  "dash_representations": map[string, object(DASHRepresentation)],
  "dash_adaptation_sets": map[string, object(DASHAdaptationSet)],
}

AdRendering

{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}

SlateRendering

{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}

VariantRendering

{
  "segment_extension": string,
  "segment_durations": object(SegmentDurations),
}

SegmentDurations

{
  "timescale": number,
  "values": [],
}

DASHRepresentation

{
  "codecs": string,
  "bandwidth": number,
  "width": number,
  "height": number,
  "frame_rate": string,
  "audio_sampling_rate": number,
  "audio_channel_config": object(SchemeIDURIAndValue),
}

DASHAdaptationSet

{
  "content_type": string,
  "mime_type": string,
  "role": object(SchemeIDURIAndValue),
  "inband_event_stream": object(SchemeIDURIAndValue),
  "min_frame_rate": string,
  "max_frame_rate": string,
  "scan_type": string,
  "start_with_sap": string,
  "segment_alignment": boolean,
  "representations": [],
}

SchemeIDURIAndValue

{
  "scheme_id_uri": string,
  "value": 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

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