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

ข้อมูลการคลิกมีข้อมูลเกี่ยวกับไอคอนการคลิกผ่าน
การแสดง 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

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

โฆษณาที่แสดงร่วม

โฆษณาที่แสดงร่วมมีข้อมูลของโฆษณาที่แสดงร่วมที่อาจแสดงพร้อมกับโฆษณา
การแสดง 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