VOD API ของการแทรกโฆษณาแบบไดนามิก

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 สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

สร้างสตรีม 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 ไม่บังคับ

ตั้งค่าเป็น true เพื่อสร้างสตรีมการใช้บีคอนฝั่งเซิร์ฟเวอร์ ค่าเริ่มต้นคือ false การติดตามของสตรีมเริ่มต้นจะเริ่มต้นจากไคลเอ็นต์และใช้คำสั่ง ping ในฝั่งเซิร์ฟเวอร์
พารามิเตอร์การกำหนดเป้าหมายของ 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