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)]

รายการ 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