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 สำหรับแหล่งที่มาของเนื้อหาและรหัสวิดีโอที่ระบุ 
 สร้างสตรีม 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 | ไม่บังคับ | ตั้งค่าเป็น  | 
| พารามิเตอร์การกําหนดเป้าหมาย 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 | stringURL การยืนยันสื่อ | 
| apple_tv | object(AppleTV)ข้อมูลที่ไม่บังคับสำหรับอุปกรณ์ AppleTV โดยเฉพาะ HLS เท่านั้น | 
| ad_breaks | [object(AdBreak)]รายการช่วงพักโฆษณา ละเว้นหากว่างเปล่า | 
AppleTV
AppleTV มีข้อมูลเฉพาะสำหรับอุปกรณ์ Apple TV| การแสดง JSON | 
|---|
| {
  "interstitials_url": string,
} | 
| ช่อง | |
|---|---|
| interstitials_url | stringURL ของโฆษณาคั่นระหว่างหน้า | 
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 | stringURL การคลิกผ่าน (ไม่บังคับ) | 
| 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 | stringURL ของไฟล์ Sidecar TTML (ไม่บังคับ) | 
| webvtt | stringURL ของไฟล์แนบ WebVTT (ไม่บังคับ) | 
SkipMetadata
SkipMetadata ให้ข้อมูลที่จําเป็นสําหรับไคลเอ็นต์ในการจัดการเหตุการณ์ข้ามสําหรับโฆษณาที่ข้ามได้| การแสดง JSON | 
|---|
| {
  "offset": number,
  "tracking_url": string,
} | 
| ช่อง | |
|---|---|
| offset | numberออฟเซตระบุระยะเวลาเป็นวินาทีที่ผู้เล่นควรรอเพื่อแสดงผลปุ่มข้ามเมื่อโฆษณาเล่นไปแล้ว ระบบจะละเว้นหากไม่ได้ระบุไว้ใน VAST | 
| tracking_url | stringTrackingURL มี 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 | stringURI ไปยังเพย์โหลด JavaScript | 
| api_framework | stringAPIFramework คือชื่อเฟรมเวิร์กวิดีโอที่ใช้รหัสยืนยัน | 
| 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 | stringURL ไปยังครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ | 
| type | stringประเภท MIME ของไฟล์ที่ระบุเป็นทรัพยากร | 
| variable_duration | booleanครีเอทีฟโฆษณานี้อาจขอขยายระยะเวลาหรือไม่ | 
| ad_parameters | stringค่าของโหนด <AdParameters> ใน VAST |