Dynamic Ad Insertion 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 เท่านั้น
การวัดผลแบบเปิด
ช่อง Verifications มีข้อมูลสําหรับการยืนยันการวัดผลแบบเปิดสําหรับสตรีมที่ไม่ใช้บีคอนฝั่งเซิร์ฟเวอร์
Verifications มีองค์ประกอบ Verification อย่างน้อย 1 รายการที่แสดงรายการทรัพยากรและข้อมูลเมตาที่จําเป็นในการยืนยันการเล่นครีเอทีฟโฆษณาด้วยโค้ดการวัดผลของบุคคลที่สาม
รองรับเฉพาะ JavaScriptResource เท่านั้น ดูข้อมูลเพิ่มเติมได้ที่ IAB Tech Lab และข้อกำหนด VAST 4.1
วิธีการ: การยืนยันสื่อ
หลังจากพบตัวระบุสื่อโฆษณาระหว่างการเล่น ให้ส่งคําขอโดยใช้ media_verification_url จากปลายทาง stream ทันที media_verification_url คือ Absolute Path
คุณไม่จำเป็นต้องส่งคำขอยืนยันสื่อสำหรับสตรีมบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์จะเป็นผู้เริ่มการยืนยันสื่อ
คำขอไปยังปลายทาง 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หากการยืนยันสื่อสําเร็จและส่งการแจ้งเตือนทั้งหมดแล้ว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 |
stringURL การยืนยันสื่อ |
apple_tv |
object(AppleTV)ข้อมูลที่ไม่บังคับสำหรับอุปกรณ์ AppleTV โดยเฉพาะ HLS เท่านั้น |
ad_breaks |
[object(AdBreak)]รายการช่วงพักโฆษณา ละเว้นหากว่างเปล่า |
AppleTV
AppleTV มีข้อมูลเฉพาะสำหรับอุปกรณ์ Apple TV| การแสดง JSON |
|---|
{
"interstitials_url": string,
} |
| ช่อง | |
|---|---|
interstitials_url |
stringURL ของโฆษณาคั่นระหว่างหน้า |
AdBreak
AdBreak อธิบายช่วงพักโฆษณาเดียวในสตรีม ซึ่งประกอบด้วยตําแหน่ง ระยะเวลา ประเภท (กลาง/ต้น/ท้าย) และรายการโฆษณา| การแสดง JSON |
|---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
| ช่อง | |
|---|---|
type |
stringประเภทช่วงพักที่ใช้ได้มีช่วงพักกลาง ช่วงพักก่อน และช่วงพักหลัง |
start |
numberตำแหน่งในสตรีมที่ช่วงพักเริ่มต้นเป็นวินาที |
duration |
numberระยะเวลาของช่วงพักโฆษณาเป็นวินาที |
ads |
[object(Ad)]รายการโฆษณา ละเว้นหากว่างเปล่า |
โฆษณา
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),
"skip_metadata": object(SkipMetadata),
"extensions": [],
} |
| ช่อง | |
|---|---|
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 |
stringURL การคลิกผ่าน (ไม่บังคับ) |
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) ไม่บังคับซึ่งควรแสดงระหว่างการเล่นโฆษณา |
skip_metadata |
object(SkipMetadata)ข้อมูลเมตาที่ไม่บังคับสําหรับโฆษณาแบบข้ามได้ หากตั้งค่าไว้ การตั้งค่านี้จะระบุว่าโฆษณาข้ามได้ รวมถึงมีวิธีการจัดการ UI การข้ามและเหตุการณ์การติดตาม |
extensions |
stringรายการโหนด <Extension> ทั้งหมดใน VAST (ไม่บังคับ) |
กิจกรรม
กิจกรรมมีประเภทกิจกรรมและเวลานำเสนอของกิจกรรม| การแสดง JSON |
|---|
{ "time": number, "type": string, } |
| ช่อง | |
|---|---|
time |
numberเวลานำเสนอของกิจกรรมนี้ |
type |
stringประเภทของเหตุการณ์นี้ |
คำบรรยาย
คำบรรยายอธิบายแทร็กคำบรรยายสำรองสำหรับสตรีมวิดีโอ โดยระบบจะจัดเก็บคำบรรยาย 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 |
stringURL ของไฟล์ Sidecar TTML (ไม่บังคับ) |
webvtt |
stringURL ของไฟล์แนบ WebVTT (ไม่บังคับ) |
SkipMetadata
SkipMetadata ให้ข้อมูลที่จําเป็นสําหรับไคลเอ็นต์ในการจัดการเหตุการณ์ข้ามสําหรับโฆษณาที่ข้ามได้| การแสดง JSON |
|---|
{
"offset": number,
"tracking_url": string,
} |
| ช่อง | |
|---|---|
offset |
numberออฟเซตระบุระยะเวลาเป็นวินาทีที่ผู้เล่นควรรอเพื่อแสดงผลปุ่มข้ามเมื่อโฆษณาเล่นไปแล้ว ระบบจะละเว้นหากไม่ได้ระบุไว้ใน VAST |
tracking_url |
stringTrackingURL มี URL ที่ควรใช้คําสั่ง ping ในเหตุการณ์ข้าม |
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 |
การยืนยัน
การยืนยันมีข้อมูลสําหรับการวัดผลแบบเปิด ซึ่งช่วยในการวัดความสามารถในการแสดงตัวโฆษณาและการยืนยันของบุคคลที่สาม ปัจจุบันรองรับเฉพาะทรัพยากร 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สตริงทึบแสงที่ส่งไปยังรหัสยืนยันการเริ่มต้นระบบ |
JavaScriptResource
JavaScriptResource มีข้อมูลสําหรับการยืนยันผ่าน JavaScript| การแสดง JSON |
|---|
{
"script_url": string,
"api_framework": string,
"browser_optional": boolean,
} |
| ช่อง | |
|---|---|
script_url |
stringURI ไปยังเพย์โหลด JavaScript |
api_framework |
stringAPIFramework คือชื่อเฟรมเวิร์กวิดีโอที่ใช้รหัสยืนยัน |
browser_optional |
booleanสคริปต์นี้เรียกใช้ได้นอกเบราว์เซอร์ไหม |
TrackingEvent
TrackingEvent มี URL ที่ไคลเอ็นต์ควรปิงในบางสถานการณ์| การแสดง 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 ของเว็บไซต์รีจิสทรีที่จัดทําแคตตาล็อกรหัสโฆษณาแบบ Universal ของครีเอทีฟโฆษณาที่เลือก |
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 |
stringURL ไปยังครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ |
type |
stringประเภท MIME ของไฟล์ที่ระบุเป็นทรัพยากร |
variable_duration |
booleanครีเอทีฟโฆษณานี้อาจขอขยายระยะเวลาหรือไม่ |
ad_parameters |
stringค่าของโหนด <AdParameters> ใน VAST |