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)] รายการ AdBreaks หากเว้นว่างไว้ |
AppleTV
Apple TV มีข้อมูลเฉพาะสำหรับอุปกรณ์ Apple TVการแสดง JSON |
---|
{ "interstitials_url": string, } |
ช่อง | |
---|---|
interstitials_url |
string URL ของโฆษณาคั่นระหว่างหน้า |
AdBreak
AdBreak อธิบายช่วงพักโฆษณาเดียวในสตรีม ซึ่งประกอบด้วยตำแหน่ง ระยะเวลา ประเภท (ตอนกลาง/ก่อน/หลัง) และรายการโฆษณาการแสดง 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
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 |