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

Dynamic Ad Insertion API ช่วยให้คุณขอและติดตามสตรีมวิดีโอออนดีมานด์ (VOD) ของการแทรกโฆษณาแบบไดนามิกได้ ระบบรองรับสตรีม HLS และ DASH

บริการ: dai.google.com

เส้นทางของเมธอด stream จะสัมพันธ์กับ https://dai.google.com

วิธีการ: สตรีม

เมธอด
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

สร้างสตรีม DAI ของ HLS สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ

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

สร้างสตรีม DAI ของ DASH สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ

คำขอ 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 สำหรับสตรีมที่ไม่ใช่การรายงานผล Conversion ฝั่งเซิร์ฟเวอร์ Verifications มีองค์ประกอบ Verification อย่างน้อย 1 รายการที่แสดงรายการ ทรัพยากรและข้อมูลเมตาที่คุณต้องใช้เพื่อยืนยันการเล่นครีเอทีฟโฆษณาด้วยโค้ดการวัดผลของบุคคลที่สาม รองรับ JavaScriptResource เท่านั้น ดูข้อมูลเพิ่มเติมได้ที่ IAB Tech Lab และข้อกำหนด VAST 4.1

วิธีการ: การยืนยันสื่อ

หลังจากพบตัวระบุสื่อโฆษณาระหว่างการเล่น ให้ส่งคำขอโดยใช้ media_verification_url จากปลายทาง stream ทันที media_verification_url คือเส้นทางที่สมบูรณ์ ไม่จำเป็นต้องส่งคำขอการยืนยันสื่อสำหรับสตรีมที่ใช้การรายงานบีคอนฝั่งเซิร์ฟเวอร์ ซึ่งเซิร์ฟเวอร์เป็นผู้เริ่มการยืนยันสื่อ

คำขอไปยังปลายทาง media verification เป็นแบบ Idempotent

เมธอด
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 หากคำขออื่นส่งการปิงอยู่แล้วในขณะนี้

รหัสสื่อโฆษณา (HLS)

ระบบจะเข้ารหัสตัวระบุสื่อโฆษณาในข้อมูลเมตาที่มีการจับเวลาของ HLS โดยใช้คีย์ TXXX, ที่สงวนไว้สำหรับเฟรม "ข้อมูลข้อความที่ผู้ใช้กำหนด" เนื้อหาของเฟรม จะไม่มีการเข้ารหัสและจะเริ่มต้นด้วยข้อความ "google_" เสมอ

ระบบควรต่อท้ายเนื้อหาข้อความทั้งหมดของเฟรมไปยัง media_verification_url สำหรับคำขอยืนยันโฆษณาแต่ละรายการ

รหัสสื่อโฆษณา (DASH)

ระบบจะแทรกตัวระบุสื่อโฆษณาลงในไฟล์ Manifest ผ่านการใช้ องค์ประกอบ EventStream ของ DASH

แต่ละ EventStream จะมี URI ของรหัสสคีมาเป็น urn:google:dai:2018 โดยจะมีเหตุการณ์ที่มีแอตทริบิวต์ messageData ซึ่งมีรหัสสื่อโฆษณาที่ขึ้นต้นด้วย "google_" ระบบควรต่อท้ายเนื้อหาทั้งหมดของแอตทริบิวต์ messageData ไปยัง media_verification_url สำหรับคำขอการยืนยันโฆษณาแต่ละรายการ

ข้อมูลการตอบกลับ

สตรีม

Stream ใช้เพื่อแสดงรายการทรัพยากรทั้งหมดสำหรับสตรีมที่สร้างขึ้นใหม่ในรูปแบบ 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)

ข้อมูลที่ไม่บังคับสำหรับอุปกรณ์ AppleTV โดยเฉพาะ HLS เท่านั้น
ad_breaks [object(AdBreak)]

รายการช่วงพักโฆษณา เว้นว่างไว้หากไม่มี

AppleTV

AppleTV มีข้อมูลเฉพาะสำหรับอุปกรณ์ 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)]

รายการโฆษณา เว้นว่างไว้หากไม่มี
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 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 การข้าม และเหตุการณ์การติดตาม
extensions string

รายการโหนด <Extension> ทั้งหมดใน VAST (ไม่บังคับ)

กิจกรรม

เหตุการณ์ประกอบด้วยประเภทเหตุการณ์และเวลาที่นำเสนอของเหตุการณ์
การแสดง JSON
{
  "time": number,
  "type": string,
}
ช่อง
time number

เวลาที่นำเสนอกิจกรรมนี้
type string

ประเภทของเหตุการณ์นี้

คำบรรยาย

คำบรรยายอธิบายแทร็กคำบรรยายแทนเสียงแบบ Sidecar สำหรับสตรีมวิดีโอ โดยจะจัดเก็บ คำบรรยาย 2 รูปแบบ ได้แก่ TTML และ WebVTT แอตทริบิวต์ TTMLPath มี URL ไปยังไฟล์ TTML Sidecar และแอตทริบิวต์ WebVTTPath มี URL ไปยังไฟล์ WebVTT Sidecar ในลักษณะเดียวกัน
การแสดง JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
ช่อง
language string

รหัสภาษา เช่น "en" หรือ "de"
language_name string

ชื่อที่สื่อความหมายของภาษา โดยจะแยกความแตกต่างของชุดคำบรรยายแทนเสียงที่เฉพาะเจาะจงหากมีหลายชุดสำหรับภาษาเดียวกัน
ttml string

URL ของไฟล์ TTML Sidecar (ไม่บังคับ)
webvtt string

URL ของไฟล์ WebVTT Sidecar (ไม่บังคับ)

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

สตริงทึบแสงที่ส่งไปยังรหัสยืนยันการเริ่มต้นระบบ

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 ที่ไคลเอ็นต์ควรปิงในบางสถานการณ์
การแสดง JSON
{
  "event": string,
  "uri": string,
}
ช่อง
event string

ประเภทของเหตุการณ์การติดตาม
uri string

เหตุการณ์การติดตามที่จะปิง

UniversalAdID

UniversalAdID ใช้เพื่อให้ตัวระบุครีเอทีฟโฆษณาที่ไม่ซ้ำกันซึ่งดูแลในระบบโฆษณา
การแสดง JSON
{
  "id_value": string,
  "id_registry": string,
}
ช่อง
id_value string

รหัสโฆษณาสากลของครีเอทีฟโฆษณาที่เลือกสำหรับโฆษณา
id_registry string

สตริงที่ใช้ระบุ URL สำหรับเว็บไซต์รีจิสทรีที่มีการจัดแคตตาล็อก Universal Ad ID ของครีเอทีฟโฆษณาที่เลือก

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