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

API การแทรกโฆษณาแบบไดนามิกช่วยให้คุณขอและติดตาม DAI ได้ วิดีโอออนดีมานด์ (VOD) รองรับสตรีม 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 การยืนยันการวัดผลสำหรับสตรีมที่ใช้บีคอนฝั่งเซิร์ฟเวอร์ 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),
  "skip_metadata": object(SkipMetadata),
}
ช่อง
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) ที่ไม่บังคับซึ่งควรแสดงระหว่างการเล่นโฆษณา
skip_metadata object(SkipMetadata)

ข้อมูลเมตาที่ไม่บังคับสำหรับโฆษณาที่ข้ามได้ หากตั้งค่าไว้ จะเป็นการระบุว่าโฆษณา สามารถข้ามได้และมีวิธีการจัดการกับ UI การข้าม และการติดตามเหตุการณ์

กิจกรรม

กิจกรรมประกอบด้วยประเภทกิจกรรมและเวลานําเสนอของกิจกรรม
การแสดง 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 string

URL ที่ไม่บังคับไปยังไฟล์ช่วยเหลือของ TTML
webvtt string

URL ที่ไม่บังคับสำหรับไปยังไฟล์ช่วยเหลือของ WebVTT

SkipMetadata

SkipMetadata จะให้ข้อมูลที่จำเป็นสำหรับลูกค้าในการจัดการเหตุการณ์การข้ามสำหรับโฆษณาที่ข้ามได้
การแสดง JSON
{
  "offset": number,
  "tracking_url": string,
}
ช่อง
offset number

ค่าออฟเซ็ตระบุระยะเวลาในหน่วยวินาทีในการเข้าสู่โฆษณาที่โปรแกรมเล่นวิดีโอ เพื่อให้ระบบแสดงปุ่มข้าม ยกเว้นหากไม่ได้ระบุไว้ใน VAST
tracking_url string

TrackingURL มี 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

การยืนยัน

การยืนยันมีข้อมูลสำหรับ 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 สำหรับเว็บไซต์รีจิสทรีที่ รหัสโฆษณาสากลของครีเอทีฟโฆษณาที่เลือกจะได้รับการจัดอยู่ในแคตตาล็อก

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 string

URL ไปยังครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ
type string

ประเภท MIME ของไฟล์ที่ระบุเป็นทรัพยากร
variable_duration boolean

ครีเอทีฟโฆษณานี้อาจขอให้ขยายระยะเวลาออกไปหรือไม่
ad_parameters string

ค่าของ <AdParameters> ใน VAST