API เชิงเส้นของการแทรกโฆษณาแบบไดนามิก

API การแทรกโฆษณาแบบไดนามิกช่วยให้คุณขอและติดตามสตรีมเชิงเส้น (LIVE) ของ DAI ได้

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

URI ด้านล่างทั้งหมดจะเกี่ยวข้องกับ https://dai.google.com

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

วิธีการ
stream POST /linear/v1/hls/event/{assetKey}/stream

สร้างสตรีม DAI สำหรับรหัสเหตุการณ์ที่ระบุ

คำขอ HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

ส่วนหัวของคำขอ

พารามิเตอร์
api‑key string

คีย์ API ที่ระบุเมื่อสร้างสตรีมต้องเป็นคีย์ที่ถูกต้องสำหรับเครือข่ายของผู้เผยแพร่

คุณสามารถส่งคีย์ API ในส่วนหัวการให้สิทธิ์ HTTP ด้วยรูปแบบต่อไปนี้แทนการใส่ไว้ในเนื้อหาของคำขอ

Authorization: DCLKDAI key="<api-key>"

พารามิเตอร์เส้นทาง

พารามิเตอร์
assetKey string

รหัสเหตุการณ์ของสตรีม
หมายเหตุ: คีย์เนื้อหาสตรีมคือตัวระบุที่อยู่ใน UI ของ Ad Manager ด้วย

เนื้อหาของคำขอ

เนื้อหาของคำขอเป็นประเภท application/x-www-form-urlencoded และมีพารามิเตอร์ต่อไปนี้

พารามิเตอร์
dai-ssb ไม่บังคับ

ตั้งค่าเป็น true เพื่อสร้างสตรีมการใช้บีคอนฝั่งเซิร์ฟเวอร์ ค่าเริ่มต้นคือ false การติดตามของสตรีมเริ่มต้นจะเริ่มต้นจากไคลเอ็นต์และใช้คำสั่ง ping ในฝั่งเซิร์ฟเวอร์
พารามิเตอร์การกำหนดเป้าหมายของ DFP ไม่บังคับ พารามิเตอร์การกำหนดเป้าหมายเพิ่มเติม
ลบล้างพารามิเตอร์ของสตรีม ไม่บังคับ ลบล้างค่าเริ่มต้นของพารามิเตอร์การสร้างสตรีม
การตรวจสอบสิทธิ์ HMAC ไม่บังคับ ตรวจสอบสิทธิ์โดยใช้โทเค็นที่ใช้ HMAC

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

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

Open Measurement

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

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

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

คำขอที่ส่งไปยังปลายทาง media verification จะอยู่ในรูปแบบเดิมเสมอ

วิธีการ
media verification GET /{media_verification_url}/{ad_media_id}

แจ้ง API ของกิจกรรมการยืนยันสื่อ

คำขอ HTTP

GET https://{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_" เสมอ

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

เมธอด: ข้อมูลเมตา

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

วิธีการ
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

เรียกข้อมูลเมตาของโฆษณา

คำขอ HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

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

หากทำสำเร็จ การตอบกลับจะส่งกลับอินสแตนซ์ของ PodMetadata

การทำงานกับข้อมูลเมตา

ข้อมูลเมตามีส่วนแยกจากกัน 3 ส่วน ได้แก่ tags, ads และโฆษณา breaks จุดแรกเข้าในข้อมูลคือส่วน tags จากนั้น ทำซ้ำแท็กต่างๆ และค้นหารายการแรกที่มีชื่อเป็นคำนำหน้าสำหรับ รหัสสื่อโฆษณาที่พบในสตรีมวิดีโอ ตัวอย่างเช่น คุณอาจมี รหัสสื่อโฆษณาที่มีลักษณะดังนี้

google_1234567890

จากนั้นจะเจอออบเจ็กต์แท็กชื่อ google_12345 ในกรณีนี้ รหัสจะตรงกับ รหัสสื่อโฆษณาของคุณ เมื่อพบออบเจ็กต์คำนำหน้าสื่อโฆษณาที่ถูกต้องแล้ว คุณจะค้นหารหัสโฆษณา รหัสช่วงพักโฆษณา และประเภทเหตุการณ์ได้ จากนั้นระบบจะใช้รหัสโฆษณาเพื่อจัดทำดัชนีออบเจ็กต์ ads และรหัสช่วงพักโฆษณาจะใช้เพื่อจัดทำดัชนีออบเจ็กต์ breaks

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

สตรีม

สตรีมใช้เพื่อแสดงผลรายการทรัพยากรสำหรับสตรีมที่สร้างขึ้นใหม่ในรูปแบบ JSON
การแสดง JSON
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
ช่อง
stream_id string

ตัวระบุสตรีม
stream_manifest string

ไฟล์ Manifest ของสตรีม ซึ่งสอดคล้องกับเพลย์ลิสต์หลักใน HLS หรือ MPD ใน DASH ช่องนี้เป็นช่องเดียวนอกเหนือจาก "stream_id" ที่ปรากฏในการตอบกลับเมื่อสร้างสตรีมแบบบีคอนฝั่งเซิร์ฟเวอร์
hls_master_playlist string

(เลิกใช้งานแล้ว) URL เพลย์ลิสต์หลักของ HLS ให้ใช้ "stream_manifest" แทน
media_verification_url string

URL การยืนยันสื่อ
metadata_url string

URL ข้อมูลเมตาของสื่อโฆษณา
session_update_url string

URL อัปเดตเซสชัน
polling_frequency number

ความถี่ในการสำรวจ URL ข้อมูลเมตาที่แนะนำในหน่วยวินาที

PodMetadata

PodMetadata มีข้อมูลเมตาเกี่ยวกับโฆษณา ช่วงพักโฆษณา และแท็กรหัสสื่อ
การแสดง JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
ช่อง
tags map[string, object(TagSegment)]

แผนที่ของกลุ่มแท็กที่จัดทำดัชนีตามคำนำหน้าแท็ก
ads map[string, object(Ad)]

แผนที่ของโฆษณาที่จัดทำดัชนีตามรหัสโฆษณา
ad_breaks map[string, object(AdBreak)]

แผนที่ของช่วงพักโฆษณาที่จัดทำดัชนีตามรหัสช่วงพักโฆษณา

TagSegment

TagSegment มีการอ้างอิงโฆษณา ช่วงพักโฆษณา และประเภทเหตุการณ์ ไม่ควรใช้คำสั่ง ping แท็กส่วนที่มี type="progress" ไปยังปลายทางการยืนยันสื่อโฆษณา
การแสดง JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
ช่อง
ad string

รหัสของโฆษณาของแท็กนี้
ad_break_id string

รหัสช่วงพักโฆษณาของแท็กนี้
type string

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

AdBreak

ช่วงพักโฆษณาจะอธิบายถึงช่วงพักโฆษณา 1 ช่วงในสตรีม ซึ่งประกอบด้วยระยะเวลา ประเภท (กลาง/ตอนต้น/โพสต์) และจำนวนโฆษณา
การแสดง JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
ช่อง
type string

ประเภทช่วงพักโฆษณาที่ถูกต้อง ได้แก่ โฆษณาตอนต้น ตอนกลาง และตอนท้าย
duration number

ระยะเวลาโฆษณาทั้งหมดของช่วงพักโฆษณานี้ หน่วยเป็นวินาที
expected_duration number

ระยะเวลาที่คาดไว้ของช่วงพักโฆษณา (เป็นวินาที) ซึ่งรวมโฆษณาทั้งหมดและแถบสเลททั้งหมด
ads number

จำนวนโฆษณาในช่วงพักโฆษณา
โฆษณาอธิบายโฆษณาในสตรีม
การแสดง JSON
{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
ช่อง
ad_break_id string

รหัสช่วงพักโฆษณาของโฆษณานี้
position number

ตำแหน่งของโฆษณานี้ในช่วงพักโฆษณา โดยเริ่มที่ 1
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 การคลิกผ่านที่ไม่บังคับ
click_tracking_urls string

URL ติดตามการคลิก (ไม่บังคับ)
verifications [object(Verification)]

รายการยืนยันของ Open Measurement (ไม่บังคับ) ซึ่งแสดงรายการทรัพยากรและข้อมูลเมตาที่จำเป็นในการเรียกใช้โค้ดการวัดของบุคคลที่สามเพื่อยืนยันการเล่นครีเอทีฟโฆษณา
slate boolean

บูลีนที่ไม่บังคับซึ่งระบุว่ารายการปัจจุบันเป็นแถบสเลท
icons [object(Icon)]

รายการไอคอนจะละเว้นหากว่างเปล่า
wrappers [object(Wrapper)]

รายการ Wrapper หากเว้นว่างไว้
universal_ad_id object(UniversalAdID)

รหัสโฆษณาสากล (ไม่บังคับ)
extensions string

รายการที่ไม่บังคับของโหนด <Extension> ทั้งหมดใน VAST
companions [object(Companion)]

โฆษณาที่แสดงร่วมซึ่งไม่บังคับที่อาจแสดงพร้อมกับโฆษณานี้
interactive_file object(InteractiveFile)

ครีเอทีฟโฆษณาแบบอินเทอร์แอกทีฟ (SIMID) ที่ไม่บังคับซึ่งควรแสดงระหว่างการเล่นโฆษณา

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

รูปภาพสำรองมีข้อมูลเกี่ยวกับรูปภาพสำรอง 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

ประเภทของเหตุการณ์การติดตาม ปัจจุบันตัวเลือกเดียวที่มีคือ "verificationNotExecuted" ตามที่ระบุไว้ในข้อกำหนด VAST 4.1
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,
}
ช่อง
click_data object(ClickData)

ข้อมูลการคลิกสำหรับการแสดงร่วมนี้
creative_type string

แอตทริบิวต์ CreativeType บนโหนด <StaticResource> ใน VAST หากนี่เป็นโฆษณาที่แสดงร่วมของประเภทแบบคงที่
height int32

ความสูงเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้
width int32

ความกว้างเป็นพิกเซลของโฆษณาที่แสดงร่วมนี้
resource string

สำหรับการแสดงร่วมแบบคงที่และ iframe จะเป็น URL ที่จะโหลดและแสดง สำหรับการแสดงร่วมแบบ HTML นี่จะเป็นข้อมูลโค้ด HTML ที่ควรแสดงเป็นโฆษณาที่แสดงร่วม
type string

ประเภทของการแสดงร่วมนี้ ซึ่งอาจเป็นแบบคงที่, iframe หรือ HTML ก็ได้

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