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

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

บริการ: dai.google.com

URI ด้านล่างทั้งหมดจะเกี่ยวข้องกับ https://dai.google.com

วิธีการ: สตรีม

เมธอด
stream POST /linear/v1/hls/event/{assetKey}/stream

สร้างสตรีม DAI สำหรับรหัสเหตุการณ์ที่ระบุ

คำขอ HTTP

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

ส่วนหัวของคำขอ

พารามิเตอร์
api‑key string

คีย์ API ซึ่งระบุเมื่อสร้างสตรีม ต้องใช้ได้กับเครือข่ายของผู้เผยแพร่โฆษณา

แทนที่จะใส่ไว้ในส่วนเนื้อหาของคำขอ คุณจะส่งคีย์ API ได้ ในส่วนหัวการให้สิทธิ์ HTTP โดยใช้รูปแบบต่อไปนี้

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

พารามิเตอร์เส้นทาง

พารามิเตอร์
assetKey string

รหัสเหตุการณ์ของสตรีม
หมายเหตุ: คีย์เนื้อหาสตรีมเป็นตัวระบุที่สามารถดูได้ใน UI ของ Ad Manager

เนื้อหาของคำขอ

เนื้อหาของคำขอเป็นประเภท application/x-www-form-urlencoded และมี พารามิเตอร์ต่อไปนี้

พารามิเตอร์
dai-ssb ไม่บังคับ

ตั้งค่าเป็น true เพื่อสร้างสตรีมการบีคอนฝั่งเซิร์ฟเวอร์ ค่าเริ่มต้นคือ false การติดตามของสตรีมเริ่มต้น เป็นคำสั่งที่ไคลเอ็นต์เริ่มและใช้คำสั่ง ping ในฝั่งเซิร์ฟเวอร์

พารามิเตอร์การกำหนดเป้าหมายของ DFP ไม่บังคับ พารามิเตอร์การกำหนดเป้าหมายเพิ่มเติม
ลบล้างพารามิเตอร์ของสตรีม ไม่บังคับ ลบล้างค่าเริ่มต้นของพารามิเตอร์การสร้างสตรีม
การตรวจสอบสิทธิ์ HMAC ไม่บังคับ ตรวจสอบสิทธิ์โดยใช้โทเค็นที่ใช้ HMAC

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

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีพารามิเตอร์ 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 ที่ได้รับจากสตรีม ปลายทางด้านบน คำขอเหล่านี้ไม่จำเป็นสำหรับการบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์จะเริ่มต้นการยืนยันสื่อ

คำขอที่ส่งไปยังปลายทาง media verification เป็นนิจพล

เมธอด
media verification GET /{media_verification_url}/{ad_media_id}

แจ้งเตือน API ของเหตุการณ์การยืนยันสื่อ

คำขอ 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 หากคำขออื่นส่งคำสั่ง ping อยู่แล้วในขณะนี้

รหัสสื่อโฆษณา (HLS)

ตัวระบุสื่อโฆษณาจะเข้ารหัสในข้อมูลเมตาแบบเวลาของ HLS โดยใช้คีย์ TXXX สงวนไว้สำหรับ "ข้อมูลข้อความที่ผู้ใช้กำหนด" ของเฟรม เนื้อหาในเฟรมจะไม่มีการเข้ารหัสและขึ้นต้นด้วยข้อความเสมอ "google_"

ควรใส่เนื้อหาข้อความทั้งหมดในเฟรมต่อท้ายการยืนยันโฆษณา URL ก่อนที่จะส่งคำขอการยืนยันโฆษณาทีละรายการ

วิธีการ: ข้อมูลเมตา

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

เมธอด
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

เรียกข้อมูลข้อมูลเมตาของโฆษณา

คำขอ HTTP

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

GET https://{metadata_url}

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

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

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

ข้อมูลเมตามี 3 ส่วนแยกกัน ได้แก่ tags, ads และโฆษณา breaks รายการ ชี้ไปที่ข้อมูลคือส่วน tags แล้วทำซ้ำผ่านแท็ก และค้นหารายการแรกที่มีชื่อเป็นคำนำหน้าสำหรับ รหัสสื่อโฆษณาในสตรีมวิดีโอ ตัวอย่างเช่น คุณสามารถ อาจมีรหัสสื่อโฆษณาที่มีลักษณะดังนี้

google_1234567890

จากนั้นคุณจะเห็นออบเจ็กต์แท็กที่ชื่อ google_12345 ในกรณีนี้ ตรงกับ รหัสสื่อโฆษณา เมื่อคุณพบออบเจ็กต์คำนำหน้าของสื่อโฆษณาที่ถูกต้องแล้ว รหัสโฆษณา รหัสช่วงพักโฆษณา และประเภทเหตุการณ์ จากนั้นจะมีการใช้รหัสโฆษณาเพื่อจัดทำดัชนี ใช้ออบเจ็กต์ ads รายการและรหัสช่วงพักโฆษณาในการจัดทำดัชนีออบเจ็กต์ breaks

ข้อมูลการตอบกลับ

สตรีม

สตรีมใช้เพื่อแสดงรายการทรัพยากรสำหรับสตรีมที่สร้างขึ้นใหม่ใน JSON
การแสดง JSON
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
ช่อง
stream_id string

ตัวระบุสตรีม GAM
stream_manifest string

URL ไฟล์ Manifest ของสตรีม ใช้สำหรับเรียกเพลย์ลิสต์เวอร์ชันแปรผันหลายตัวแปรใน HLS หรือ MPD ใน DASH
hls_master_playlist string

(เลิกใช้งานแล้ว) URL ของเพลย์ลิสต์หลายรูปแบบของ HLS ใช้ "stream_manifest" แทน
media_verification_url string

URL การยืนยันสื่อที่ใช้เป็นปลายทางฐานสำหรับการติดตามเหตุการณ์การเล่น
metadata_url string

URL ของข้อมูลเมตาที่ใช้ในการสำรวจข้อมูลเป็นระยะเกี่ยวกับเหตุการณ์โฆษณาสตรีมที่กำลังจะมาถึง
session_update_url string

URL อัปเดตของเซสชันที่ใช้อัปเดตพารามิเตอร์การกำหนดเป้าหมายสำหรับสตรีมนี้ ระบบจะบันทึกค่าเดิมสำหรับพารามิเตอร์การกำหนดเป้าหมายระหว่างคำขอสร้างสตรีมเริ่มต้น
polling_frequency number

ความถี่ในการสำรวจ (หน่วยเป็นวินาที) เมื่อขอmetadata_url หรือ cardbeat_url

PodMetadata

PodMetadata มีข้อมูลเมตาในโฆษณา ช่วงพักโฆษณา และแท็กรหัสสื่อ
การแสดง JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
ช่อง
tags map[string, object(TagSegment)]

แผนที่แสดงส่วนแท็กที่จัดทำดัชนีโดยคำนำหน้าแท็ก
ads map[string, object(Ad)]

แผนที่โฆษณาที่จัดทำดัชนีตามรหัสโฆษณา
ad_breaks map[string, object(AdBreak)]

แผนที่ช่วงพักโฆษณาซึ่งจัดทำดัชนีตามรหัสช่วงพักโฆษณา

TagSegment

กลุ่มแท็กมีการอ้างอิงถึงโฆษณา ช่วงพักโฆษณา และประเภทเหตุการณ์ กลุ่มแท็กที่มี type="progress" ไม่ควรใช้คำสั่ง ping ไปยังสื่อโฆษณา ปลายทางการยืนยัน
การแสดง JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
ช่อง
ad string

รหัสโฆษณาของแท็กนี้
ad_break_id string

รหัสช่วงพักโฆษณาของแท็กนี้
type string

ประเภทเหตุการณ์ของแท็กนี้

AdBreak

AdBreak อธิบายช่วงพักโฆษณาเดียวในสตรีม โดยประกอบด้วยระยะเวลา ประเภท (ช่วงกลาง/ก่อน/หลัง) และจำนวนโฆษณา
การแสดง JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
ช่อง
type string

ประเภทช่วงพักโฆษณาที่ใช้ได้ ได้แก่ ตอนต้น ตอนกลาง และตอนท้าย
duration number

ระยะเวลาโฆษณาทั้งหมดของช่วงพักโฆษณานี้เป็นวินาที
expected_duration number

ระยะเวลาที่คาดไว้ของช่วงพักโฆษณา (เป็นวินาที) รวมถึงโฆษณาทั้งหมดและแถบสเลททั้งหมด
ads number

จำนวนโฆษณาในช่วงพักโฆษณา
โฆษณาอธิบายโฆษณาในสตรีม
การแสดง JSON
{
  "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),
}
ช่อง
ad_break_id string

รหัสช่วงพักโฆษณาของโฆษณานี้
position number

ตำแหน่งของโฆษณานี้ในช่วงพักโฆษณา โดยเริ่มที่ 1
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

URL การคลิกผ่านที่ไม่บังคับ
click_tracking_urls string

URL ติดตามการคลิกที่ไม่บังคับ
verifications [object(Verification)]

รายการการยืนยัน Open Measurement ที่ไม่บังคับซึ่งจะแสดงรายการทรัพยากร และข้อมูลเมตาที่จำเป็นสำหรับการเรียกใช้โค้ดการวัดของบุคคลที่สามเพื่อยืนยัน ในการเล่นครีเอทีฟโฆษณา
slate boolean

บูลีนที่ไม่บังคับที่ระบุว่ารายการปัจจุบันคือแถบสเลท
icons [object(Icon)]

รายการไอคอน ละเว้นหากว่างเปล่า
wrappers [object(Wrapper)]

รายการ Wrapper หากว่างเปล่า
universal_ad_id object(UniversalAdID)

รหัสโฆษณาสากล (ไม่บังคับ)
extensions string

รายการที่ไม่บังคับของ <Extension> ทั้งหมด ใน VAST
companions [object(Companion)]

โฆษณาที่แสดงร่วมกัน (ไม่บังคับ) ที่อาจแสดงพร้อมกับโฆษณานี้
interactive_file object(InteractiveFile)

ครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ (SIMID) ที่ไม่บังคับซึ่งควรแสดงระหว่างการเล่นโฆษณา

Icon

ไอคอนมีข้อมูลเกี่ยวกับไอคอน VAST
การแสดง JSON
{
  "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,
}
ช่อง
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

ClickData มีข้อมูลเกี่ยวกับการคลิกผ่านไอคอน
การแสดง JSON
{
  "url": string,
}
ช่อง
url string

FallbackImage

FallbackImage มีข้อมูลเกี่ยวกับรูปภาพทางเลือก VAST
การแสดง JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
ช่อง
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Wrapper มีข้อมูลเกี่ยวกับโฆษณา Wrapper และไม่มี รหัสดีล หากมี
การแสดง JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
ช่อง
system string

ตัวระบุระบบโฆษณา
ad_id string

รหัสโฆษณาที่ใช้สำหรับโฆษณา Wrapper
creative_id string

รหัสครีเอทีฟโฆษณาที่ใช้สำหรับโฆษณา Wrapper
creative_ad_id string

รหัสโฆษณาที่ใช้สำหรับโฆษณา Wrapper
deal_id string

รหัสดีลที่ไม่บังคับสำหรับโฆษณา Wrapper

การยืนยัน

การยืนยันมีข้อมูลสำหรับ Open Measurement ซึ่งช่วยให้ การวัดการมองเห็นโฆษณาและการยืนยันโดยบุคคลที่สาม ปัจจุบันรองรับเฉพาะทรัพยากร JavaScript เท่านั้น ดู https://iabtechlab.com/standards/open-measurement-sdk/
การแสดง JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
ช่อง
vendor string

ผู้ให้บริการตรวจสอบ
java_script_resources [object(JavaScriptResource)]

รายการทรัพยากร JavaScript สำหรับการยืนยัน
tracking_events [object(TrackingEvent)]

รายการเหตุการณ์การติดตามสำหรับการยืนยัน
parameters string

สตริงที่คลุมเครือที่ส่งไปยังรหัสยืนยัน Bootstrap

JavaScriptResource

JavaScriptResource มีข้อมูลสำหรับการยืนยันผ่าน JavaScript
การแสดง JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
ช่อง
script_url string

URL ไปยังเพย์โหลด JavaScript
api_framework string

APIFramework คือชื่อของเฟรมเวิร์กวิดีโอที่ใช้องค์ประกอบ รหัสยืนยัน
browser_optional boolean

สามารถเรียกใช้สคริปต์นี้ภายนอก เบราว์เซอร์

TrackingEvent

TrackingEvent มี URL ที่ไคลเอ็นต์ควรใช้คำสั่ง ping ใน เท่านั้น
การแสดง JSON
{
  "event": string,
  "uri": string,
}
ช่อง
event string

ประเภทของเหตุการณ์การติดตาม
uri string

เหตุการณ์การติดตามที่จะใช้คำสั่ง ping

UniversalAdID

UniversalAdID ใช้เพื่อจัดเตรียมตัวระบุครีเอทีฟโฆษณาที่ไม่ซ้ำกัน และดูแลได้ทั่วทั้งระบบโฆษณา
การแสดง JSON
{
  "id_value": string,
  "id_registry": string,
}
ช่อง
id_value string

รหัสโฆษณาสากลของครีเอทีฟโฆษณาที่เลือกสำหรับโฆษณานั้น
id_registry string

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

Companion

โฆษณาที่แสดงร่วมมีข้อมูลสำหรับโฆษณาที่แสดงร่วมซึ่งอาจแสดงอยู่ พร้อมกับโฆษณา
การแสดง JSON
{
  "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)],
}
ช่อง
click_data object(ClickData)

ข้อมูลการคลิกสำหรับโฆษณาที่แสดงร่วมนี้
creative_type string

แอตทริบิวต์ CreativeType ใน <StaticResource> ใน VAST หาก นี่เป็นการแสดงร่วมของประเภทคงที่
height int32

ความสูงเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้
width int32

ความกว้างเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้
resource string

สำหรับการแสดงร่วมแบบคงที่และ iframe นี่คือ URL ที่จะโหลดและ แสดงอยู่ สำหรับการแสดงร่วม HTML นี่คือข้อมูลโค้ด HTML ที่ควร แสดงเป็นโฆษณาที่แสดงร่วม
type string

ประเภทของการแสดงร่วมนี้ ซึ่งอาจเป็นแบบคงที่, iframe หรือ HTML
ad_slot_id string

รหัสช่องโฆษณาสำหรับโฆษณาที่แสดงร่วมนี้
api_framework string

เฟรมเวิร์ก API สำหรับโฆษณาที่แสดงร่วมนี้
tracking_events [object(TrackingEvent)]

รายการเหตุการณ์การติดตามสำหรับโฆษณาที่แสดงร่วมนี้

InteractiveFile

InteractiveFile มีข้อมูลสำหรับครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ (เช่น SIMID) ซึ่งควรแสดงระหว่างการเล่นโฆษณา
การแสดง JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
ช่อง
resource string

URL ไปยังครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ
type string

ประเภท MIME ของไฟล์ที่ระบุเป็นทรัพยากร
variable_duration boolean

ครีเอทีฟโฆษณานี้อาจขอให้ขยายระยะเวลาออกไปหรือไม่
ad_parameters string

ค่าของ <AdParameters> ใน VAST