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 รหัสเหตุการณ์ของสตรีม |
เนื้อหาของคำขอ
เนื้อหาของคำขอเป็นประเภท application/x-www-form-urlencoded
และมี
พารามิเตอร์ต่อไปนี้
พารามิเตอร์ | ||
---|---|---|
dai-ssb |
ไม่บังคับ | ตั้งค่าเป็น |
พารามิเตอร์การกำหนดเป้าหมายของ 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 |