API การแทรกโฆษณาแบบไดนามิกช่วยให้คุณขอและติดตามสตรีมวิดีโอตามคำขอ (VOD) ของ DAI ได้ รองรับสตรีม HLS และ DASH
บริการ: dai.google.com
เส้นทางของเมธอด stream
จะสัมพัทธ์กับ https://dai.google.com
วิธีการ: สตรีม
วิธีการ | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
สร้างสตรีม HLS DAI สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ
สร้างสตรีม DASH DAI สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ |
คำขอ HTTP
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
ส่วนหัวของคำขอ
พารามิเตอร์ | |
---|---|
api‑key |
string คีย์ API ที่ระบุเมื่อสร้างสตรีมต้องเป็นคีย์ที่ถูกต้องสำหรับเครือข่ายของผู้เผยแพร่ คุณสามารถส่งคีย์ API ในส่วนหัวการให้สิทธิ์ HTTP ด้วยรูปแบบต่อไปนี้แทนการใส่ไว้ในเนื้อหาของคำขอ Authorization: DCLKDAI key="<api-key>" |
พารามิเตอร์เส้นทาง
พารามิเตอร์ | |
---|---|
content-source |
string รหัส CMS ของสตรีม |
video-id |
string รหัสวิดีโอของสตรีม |
เนื้อหาของคำขอ
เนื้อหาของคำขอเป็นประเภท application/x-www-form-urlencoded
และมีพารามิเตอร์ต่อไปนี้
พารามิเตอร์ | ||
---|---|---|
dai-ssb |
ไม่บังคับ | ตั้งค่าเป็น |
พารามิเตอร์การกำหนดเป้าหมายของ DFP | ไม่บังคับ | พารามิเตอร์การกำหนดเป้าหมายเพิ่มเติม |
ลบล้างพารามิเตอร์ของสตรีม | ไม่บังคับ | ลบล้างค่าเริ่มต้นของพารามิเตอร์การสร้างสตรีม |
การตรวจสอบสิทธิ์ HMAC | ไม่บังคับ | ตรวจสอบสิทธิ์โดยใช้โทเค็นที่ใช้ HMAC |
เนื้อหาการตอบกลับ
หากทำสำเร็จ เนื้อหาการตอบกลับจะมี Stream
ใหม่ สำหรับสตรีมการบีคอนฝั่งเซิร์ฟเวอร์ Stream
นี้จะมีเฉพาะช่อง stream_id
และ stream_manifest
Open Measurement
ช่อง Verifications
มีข้อมูลสำหรับการยืนยัน Open Measurement สำหรับสตรีมแบบใช้บีคอนฝั่งเซิร์ฟเวอร์
Verifications
มีองค์ประกอบ Verification
อย่างน้อย 1 รายการที่ระบุทรัพยากรและข้อมูลเมตาที่คุณต้องใช้เพื่อยืนยันการเล่นครีเอทีฟโฆษณาด้วยโค้ดการวัดของบุคคลที่สาม
รองรับ JavaScriptResource
เท่านั้น สำหรับข้อมูลเพิ่มเติม โปรดดู IAB Tech Lab และข้อกำหนด VAST 4.1
วิธีการ: การยืนยันสื่อ
หลังจากพบตัวระบุสื่อโฆษณาในระหว่างการเล่น ให้ส่งคำขอทันทีโดยใช้ media_verification_url
จากปลายทาง stream
media_verification_url
เป็นเส้นทางสัมบูรณ์
ซึ่งคำขอยืนยันสื่ออาจไม่จำเป็นสำหรับสตรีมแบบบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์จะเริ่มต้นการยืนยันสื่อ
คำขอที่ส่งไปยังปลายทาง media verification
จะอยู่ในรูปแบบเดิมเสมอ
วิธีการ | |
---|---|
media verification |
GET {media_verification_url}/{ad_media_id}
แจ้ง API ของกิจกรรมการยืนยันสื่อ |
คำขอ HTTP
GET {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_"
เสมอ
ควรแนบเนื้อหาข้อความทั้งหมดของเฟรมต่อท้าย media_verification_url สำหรับคำขอการยืนยันโฆษณาแต่ละรายการ
รหัสสื่อโฆษณา (DASH)
ระบบจะแทรกตัวระบุสื่อของโฆษณาลงในไฟล์ Manifest โดยใช้องค์ประกอบ EventStream
ของ DASH
EventStream
แต่ละรายการจะมี URI รหัสรูปแบบเป็น urn:google:dai:2018
โดยจะมีเหตุการณ์ที่มีแอตทริบิวต์ messageData
ซึ่งมีรหัสสื่อโฆษณาที่ขึ้นต้นด้วย “google_”
เนื้อหาทั้งหมดของแอตทริบิวต์ messageData
ควรต่อท้าย media_verification_url สำหรับคำขอการยืนยันโฆษณาแต่ละรายการ
ข้อมูลการตอบกลับ
สตรีม
สตรีมใช้ในการแสดงผลรายการทรัพยากรทั้งหมดสำหรับสตรีมที่สร้างขึ้นใหม่ในรูปแบบ JSONการแสดง JSON |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
ช่อง | |
---|---|
stream_id |
string ตัวระบุสตรีม |
total_duration |
number ระยะเวลาการสตรีมเป็นวินาที |
content_duration |
number ระยะเวลาของเนื้อหาเป็นวินาที โดยไม่รวมโฆษณา |
valid_for |
string สตรีมระยะเวลาใช้ได้ในรูปแบบ "00h00m00s" |
valid_until |
string วันที่ที่ใช้สตรีมได้จนถึง ในรูปแบบ RFC 3339 |
subtitles |
[object(Subtitle)] รายการคำบรรยาย หากเว้นว่างไว้ HLS เท่านั้น |
hls_master_playlist |
string (เลิกใช้งานแล้ว) URL เพลย์ลิสต์หลักของ HLS ใช้stream_manifest HLS เท่านั้น |
stream_manifest |
string ไฟล์ Manifest ของสตรีม ตรงกับเพลย์ลิสต์หลักใน HLS และ MPD ใน DASH ช่องนี้เป็นช่องเดียวนอกเหนือจาก "stream_id" ที่แสดงในการตอบกลับเมื่อสร้างสตรีมแบบบีคอนฝั่งเซิร์ฟเวอร์ |
media_verification_url |
string URL การยืนยันสื่อ |
apple_tv |
object(AppleTV) ข้อมูลเพิ่มเติมสำหรับอุปกรณ์ Apple TV โดยเฉพาะ HLS เท่านั้น |
ad_breaks |
[object(AdBreak)] รายการช่วงพักโฆษณา หากเว้นว่างไว้ |
AppleTV
Apple TV มีข้อมูลเฉพาะสำหรับอุปกรณ์ Apple TVการแสดง JSON |
---|
{ "interstitials_url": string, } |
ช่อง | |
---|---|
interstitials_url |
string URL ของโฆษณาคั่นระหว่างหน้า |
AdBreak
ช่วงพักโฆษณาจะอธิบายถึงช่วงพักโฆษณา 1 ช่วงในสตรีม ซึ่งประกอบด้วยตำแหน่ง ระยะเวลา ประเภท (กลาง/ก่อน/หลัง) และรายการโฆษณาการแสดง JSON |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
ช่อง | |
---|---|
type |
string ประเภทช่วงพักโฆษณาที่ถูกต้อง ได้แก่ ช่วงกลาง ตอนต้น และตอนท้าย |
start |
number ตำแหน่งในสตรีมที่ช่วงพักเริ่มขึ้นเป็นวินาที |
duration |
number ระยะเวลาของช่วงพักโฆษณา หน่วยเป็นวินาที |
ads |
[object(Ad)] รายการโฆษณา หากเว้นว่างไว้ |
โฆษณา
โฆษณาอธิบายโฆษณาในสตรีม ซึ่งประกอบด้วยตำแหน่งของโฆษณาในช่วงพัก ระยะเวลาของโฆษณา และข้อมูลเมตาที่ไม่บังคับบางส่วนการแสดง JSON |
---|
{ "seq": number, "start": 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, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
ช่อง | |
---|---|
seq |
number ตำแหน่งของโฆษณาในช่วงพัก |
start |
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 URL การคลิกผ่านที่ไม่บังคับ |
icons |
[object(Icon)] รายการไอคอนจะละเว้นหากว่างเปล่า |
wrappers |
[object(Wrapper)] รายการ Wrapper หากเว้นว่างไว้ |
events |
[object(Event)] รายการเหตุการณ์ในโฆษณา |
verifications |
[object(Verification)] รายการยืนยันของ Open Measurement (ไม่บังคับ) ซึ่งแสดงรายการทรัพยากรและข้อมูลเมตาที่จำเป็นในการเรียกใช้โค้ดการวัดของบุคคลที่สามเพื่อยืนยันการเล่นครีเอทีฟโฆษณา |
universal_ad_id |
object(UniversalAdID) รหัสโฆษณาสากล (ไม่บังคับ) |
companions |
[object(Companion)] โฆษณาที่แสดงร่วมซึ่งไม่บังคับที่อาจแสดงพร้อมกับโฆษณานี้ |
interactive_file |
object(InteractiveFile) ครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ (SIMID) ที่ไม่บังคับซึ่งควรแสดงระหว่างการเล่นโฆษณา |
เหตุการณ์
กิจกรรมประกอบด้วยประเภทกิจกรรมและเวลานำเสนอกิจกรรมการแสดง JSON |
---|
{ "time": number, "type": string, } |
ช่อง | |
---|---|
time |
number เวลานำเสนอของกิจกรรมนี้ |
type |
string ประเภทของกิจกรรมนี้ |
Subtitle
ชื่อรองอธิบายแทร็กคำบรรยายไฟล์ช่วยเหลือสำหรับสตรีมวิดีโอ โดยจะเก็บคำบรรยาย 2 รูปแบบ ได้แก่ TTML และ WebVTT แอตทริบิวต์ TTMLPath มี URL ไปยังไฟล์ช่วยเหลือ TTML และแอตทริบิวต์ WebVTTPath จะมี URL ไปยังไฟล์ช่วยเหลือของ WebVTT ในทำนองเดียวกันการแสดง JSON |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
ช่อง | |
---|---|
language |
string รหัสภาษา เช่น "en" หรือ "de" |
language_name |
string ชื่อที่สื่อความหมายของภาษา ซึ่งจะแยกความแตกต่างของชุดคำบรรยายที่เจาะจง หากมีหลายชุดสำหรับภาษาเดียวกัน |
ttml |
string URL ที่ไม่บังคับสำหรับไฟล์ไฟล์ช่วยเหลือของ TTML |
webvtt |
string URL ที่ไม่บังคับสำหรับไฟล์ช่วยเหลือของ WebVTT |
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
รูปภาพสำรองมีข้อมูลเกี่ยวกับรูปภาพสำรอง 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 URI ไปยังเพย์โหลด JavaScript |
api_framework |
string APIFramework คือชื่อของเฟรมเวิร์กวิดีโอที่ใช้รหัสยืนยัน |
browser_optional |
boolean สคริปต์นี้ทำงานนอกเบราว์เซอร์ได้หรือไม่ |
TrackingEvent
TrackingEvent มี URL ที่ไคลเอ็นต์ควรใช้คำสั่ง ping ในสถานการณ์บางอย่างการแสดง JSON |
---|
{ "event": string, "uri": string, } |
ช่อง | |
---|---|
event |
string ประเภทของเหตุการณ์การติดตาม ปัจจุบันตัวเลือกเดียวที่มีคือ "verificationNotExecuted" ตามที่ระบุไว้ในข้อกำหนด VAST 4.1 |
uri |
string เหตุการณ์การติดตามที่จะใช้คำสั่ง ping |
UniversalAdID
UniversalAdID ใช้เพื่อให้ตัวระบุครีเอทีฟโฆษณาที่ไม่ซ้ำกันที่เก็บไว้ในระบบโฆษณาต่างๆการแสดง JSON |
---|
{ "id_value": string, "id_registry": string, } |
ช่อง | |
---|---|
id_value |
string รหัสโฆษณาสากลของครีเอทีฟโฆษณาที่เลือกสำหรับโฆษณา |
id_registry |
string สตริงที่ใช้ระบุ URL ของเว็บไซต์รีจิสทรี ซึ่งเป็นที่ที่รหัสโฆษณา Universal ของครีเอทีฟโฆษณาที่เลือกเป็นแคตตาล็อก |
โฆษณาที่แสดงร่วม
โฆษณาที่แสดงร่วมมีข้อมูลของโฆษณาที่แสดงร่วมที่อาจแสดงพร้อมกับโฆษณาการแสดง JSON |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, } |
ช่อง | |
---|---|
click_data |
object(ClickData) ข้อมูลการคลิกสำหรับการแสดงร่วมนี้ |
creative_type |
string แอตทริบิวต์ CreativeType บนโหนด <StaticResource> ใน VAST หากนี่เป็นโฆษณาที่แสดงร่วมของประเภทแบบคงที่ |
height |
int32 ความสูงเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้ |
width |
int32 ความกว้างเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้ |
resource |
string สำหรับการแสดงร่วมแบบคงที่และ iframe จะเป็น URL ที่จะโหลดและแสดง สำหรับการแสดงร่วมแบบ HTML นี่จะเป็นข้อมูลโค้ด HTML ที่ควรแสดงเป็นโฆษณาที่แสดงร่วม |
type |
string ประเภทของการแสดงร่วมนี้ ซึ่งอาจเป็นแบบคงที่, iframe หรือ HTML ก็ได้ |
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 |