API เชิงเส้นของการแทรกโฆษณาแบบไดนามิก

Dynamic Ad Insertion API ช่วยให้คุณขอและติดตามสตรีมเชิงเส้น (สด) ของการแทรกโฆษณาแบบไดนามิกได้

บริการ: 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 ใหม่ สำหรับสตรีมที่ใช้บีคอนฝั่งเซิร์ฟเวอร์ Stream จะมีเฉพาะฟิลด์ stream_id และ stream_manifest เท่านั้น

Open Measurement

DAI API มีข้อมูลสำหรับการยืนยัน Open Measurement ในฟิลด์ Verifications ฟิลด์นี้มีองค์ประกอบอย่างน้อย 1 รายการ Verification ซึ่งแสดงรายการทรัพยากรและข้อมูลเมตาที่จำเป็นต่อการเรียกใช้ โค้ดการวัดผลโดยบุคคลที่สามเพื่อยืนยันการเล่นครีเอทีฟโฆษณา รองรับเฉพาะ JavaScriptResource ดูข้อมูลเพิ่มเติมได้ที่ IAB Tech Lab และ ข้อกำหนด VAST 4.1

วิธีการ: การยืนยันสื่อ

หลังจากพบตัวระบุสื่อโฆษณาระหว่างการเล่น ให้ส่งคำขอทันทีโดยใช้ media_verification_url ที่ได้จากปลายทาง stream คำขอเหล่านี้ไม่จำเป็นสำหรับสตรีมที่ใช้การรายงานบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์เป็นผู้เริ่มการยืนยันสื่อ

คำขอไปยังปลายทาง media verification เป็นแบบ Idempotent

คำขอ HTTP

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

เนื้อหาการตอบกลับ

media verification จะแสดงการตอบกลับต่อไปนี้

• HTTP/1.1 204 No Content หากการยืนยันสื่อสำเร็จและส่งการ Ping ทั้งหมดแล้ว
• 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 จะแสดงข้อมูลที่ใช้สร้างโฆษณา UI ปลายทางข้อมูลเมตาไม่พร้อมใช้งานสำหรับสตรีมที่ใช้การส่งบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์มีหน้าที่เริ่มการยืนยันสื่อโฆษณา

คำขอ HTTP

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

GET https://{metadata_url}

พารามิเตอร์การค้นหา

เนื้อหาการตอบกลับ

หากทำสำเร็จ การตอบกลับจะแสดงอินสแตนซ์ของ PodMetadata

การทำงานกับข้อมูลเมตา

ข้อมูลเมตามี 3 ส่วนที่แยกกัน ได้แก่ 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,
}