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  |