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

Dynamic Ad Insertion 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 การติดตามของสตรีมเริ่มต้นจะเริ่มต้นโดยไคลเอ็นต์และมีการปิงฝั่งเซิร์ฟเวอร์
พารามิเตอร์การกําหนดเป้าหมาย DFP ไม่บังคับ พารามิเตอร์การกําหนดเป้าหมายเพิ่มเติม
ลบล้างพารามิเตอร์ของสตรีม ไม่บังคับ ลบล้างค่าเริ่มต้นของพารามิเตอร์การสร้างสตรีม
การตรวจสอบสิทธิ์ HMAC ไม่บังคับ ตรวจสอบสิทธิ์โดยใช้โทเค็นที่ใช้ HMAC

เนื้อหาการตอบกลับ

หากทำสำเร็จ เนื้อหาการตอบกลับจะมี Stream ใหม่ สำหรับสตรีมบีคอนฝั่งเซิร์ฟเวอร์ Stream จะมีเฉพาะช่อง stream_id และ stream_manifest เท่านั้น

การวัดผลแบบเปิด

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

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

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

คำขอไปยังปลายทาง 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 หากการยืนยันสื่อสําเร็จและส่งการแจ้งเตือนทั้งหมดแล้ว
  • 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)

ข้อมูลที่ไม่บังคับสำหรับอุปกรณ์ 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

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

คำบรรยาย

คำบรรยายอธิบายแทร็กคำบรรยายสำรองสำหรับสตรีมวิดีโอ โดยระบบจะจัดเก็บคำบรรยาย 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 ของไฟล์ Sidecar 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

การยืนยัน

การยืนยันมีข้อมูลสําหรับการวัดผลแบบเปิด ซึ่งช่วยในการวัดความสามารถในการแสดงตัวโฆษณาและการยืนยันของบุคคลที่สาม ปัจจุบันรองรับเฉพาะทรัพยากร 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

เหตุการณ์การติดตามที่จะส่งคําสั่ง ping

UniversalAdID

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

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

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

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