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

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

บริการ: 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 ช่องนี้มีองค์ประกอบ Verification อย่างน้อย 1 รายการที่แสดงทรัพยากรและข้อมูลเมตาที่จำเป็นต่อการเรียกใช้โค้ดการวัดของบุคคลที่สามเพื่อยืนยันการเล่นครีเอทีฟโฆษณา รองรับเฉพาะ 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

กลุ่มแท็กมีการอ้างอิงถึงโฆษณา ช่วงพักโฆษณา และประเภทเหตุการณ์ ไม่ควรใช้ TagSegment ที่มี type="progress" ในปลายทางการยืนยันสื่อโฆษณา
การแสดง 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 ของเว็บไซต์รีจิสทรีที่มีแคตตาล็อกรหัสโฆษณาสากลของครีเอทีฟโฆษณาที่เลือก

โฆษณาที่แสดงร่วม

โฆษณาที่แสดงร่วมมีข้อมูลสำหรับโฆษณาที่แสดงร่วมซึ่งอาจแสดงควบคู่ไปกับโฆษณา
การแสดง 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