API สำหรับการแทรกโฆษณาแบบไดนามิก (DAI) ให้คุณเข้าถึงสตรีมที่สร้างรายได้ที่ไม่รองรับ IMA SDK (เช่น สมาร์ททีวี) โดยต้องใช้ IMA ดังกล่าวในแพลตฟอร์มที่มีให้บริการ API ข้างต้นรองรับฟีเจอร์ที่มีอยู่ทั้งหมดของ DAI แต่ผู้เผยแพร่โฆษณาจะต้องทำการติดตั้งใช้งาน
ข้อกำหนดเมื่อใช้ API
ผู้เผยแพร่โฆษณาต้องติดตั้งใช้งานฟังก์ชันต่อไปนี้เมื่อใช้ API
- การเข้าถึงสตรีม DAI ผ่านปลายทาง HTTP และการประมวลผลการตอบสนองแบบ JSON
- การสร้างพารามิเตอร์ของ API และการกำหนดเป้าหมายคีย์-ค่า
- การสร้างประสบการณ์ของผู้ใช้ (เช่น การคลิกผ่านและไอคอน)
- ฟังเหตุการณ์ ID3 ในโปรแกรมเล่นเพื่อใช้งานส่วนควบคุมโปรแกรมเล่นและการติดตาม/การวัดผลโฆษณาสำหรับทั้งสตรีมแบบสดและ VOD
- การใช้ลักษณะการทำงานแบบสครับ, Snapback และฟังก์ชันการบุ๊กมาร์ก
- การเลือกรูปแบบการสตรีม: HLS หรือ DASH
คุณใช้ข้อมูลต่อไปนี้เพื่อขอและประมวลผลสตรีมผ่าน API สําหรับวิดีโอตามคําขอหรือสตรีมเชิงเส้นแบบสดได้
วิดีโอตามคำขอ (VOD)
วงจรการใช้งาน VOD API เป็นแบบง่ายๆ ตั้งแต่การสร้างสตรีมไปจนถึงการยืนยันการเล่นโฆษณา ดังนี้
-
ขอสตรีมด้วย HTTP POST โดยใช้รหัสแหล่งที่มาของเนื้อหา (
cmsid
) และรหัสวิดีโอ (vid
) โดยมีคีย์ API หรือโทเค็น HMAC และพารามิเตอร์การกำหนดเป้าหมายโฆษณาhttps://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream
-
ประมวลผลการตอบสนองสำหรับไฟล์ Manifest การเล่นเนื้อหา คำบรรยาย/คำบรรยายวิดีโอ ช่วงพักโฆษณา และข้อมูลจังหวะเวลาของเนื้อหา
{
"content_duration": 123.451,
"stream_manifest": "https://dai.google.com/.../master.m3u8",
"media_verification_url": "https://dai.google.com/.../media/",
"stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0",
"total_duration": 163.451,
"valid_for": "8h0m0s",
"valid_until": "2018-05-16T23:21:16.558053292-07:00",
"ad_breaks": [...]
}
-
สำหรับช่วงพักโฆษณาแต่ละครั้ง ให้ประมวลผลรายละเอียดโฆษณาแต่ละอย่างสำหรับองค์ประกอบโฆษณาต่างๆ เช่น ข้อมูลการคลิกผ่าน โฆษณาที่แสดงร่วม และระยะเวลาของช่วงพักโฆษณาในการแสดงผล UI
{
"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400",
"description": "ตัวอย่างโฆษณาตอนต้น",
"duration": 10,
"seq": 1,
"title": "ตัวอย่างโฆษณาตอนต้น"
}
-
สำหรับโฆษณาแต่ละรายการ ให้ทริกเกอร์
media_verification_url
โดยเอาค่า ID3 จากการเล่นสื่อโฆษณามาต่อท้ายhttps://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
เหตุการณ์ความคืบหน้า (Progress) มีไว้เพื่อแยกความแตกต่างระหว่างการเล่นภายในและภายนอกช่วงพักโฆษณา และไม่ใช้สำหรับจุดประสงค์อื่นๆ ในการติดตามโฆษณา
คุณระบุเหตุการณ์ความคืบหน้าได้โดยค้นหาไฟล์ JSON ของข้อมูลเมตาเพื่อดูตัวระบุสื่อและยืนยันว่ามีการตั้งค่าฟิลด์ type
เป็น progress
คุณใช้ Progress ID3 ได้ เช่น เพื่อบล็อกส่วนควบคุมวิดีโอ
สตรีมแบบสด
วงจรการใช้งาน API เชิงเส้นเป็นแบบง่ายๆ ตั้งแต่การสร้างสตรีมไปจนถึงการยืนยันการเล่นโฆษณา ดังนี้
-
ขอสตรีมด้วย HTTP POST โดยใช้รหัสเหตุการณ์ พร้อมด้วยคีย์ API หรือโทเค็น HMAC และพารามิเตอร์การกำหนดเป้าหมายโฆษณา
https://dai.google.com/linear/v1/hls/event/<eventid>/stream
https://dai.google.com/linear/v1/dash/event/<eventid>/stream -
ประมวลผลการตอบสนองสำหรับไฟล์ Manifest การเล่นเนื้อหา คำบรรยาย/คำบรรยายวิดีโอ ช่วงพักโฆษณา และข้อมูลจังหวะเวลาของเนื้อหา
{
"stream_manifest": "https://dai.google.com/linear/.../master.m3u8",
"media_verification_url": "https://dai.google.com/linear/.../media/",
"metadata_url": "https://dai.google.com/linear/.../metadata",
"polling_frequency": 10,
"stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",
}
-
ขอข้อมูลเมตาโฆษณาตามความถี่ในการตรวจสอบสถานะ (Polling Frequency) หรือสำหรับรหัสสื่อโฆษณา ID3 แต่ละรหัส โดยใส่รหัสสื่อโฆษณาต่อท้าย URL ข้อมูลเมตาในพารามิเตอร์การค้นหา
{
"ad_breaks": {
"0001127859": {
"ads": 3,
"duration": 30,
"type": "mid"
}
},
"ads": {
"0001127859_ad2": {
"ad_break_id": "0001127859",
"ad_id": "39135088",
"ad_system": "GDFP",
"clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...",
"creative_id": "103990016608",
"description": "ตัวอย่างโฆษณาเชิงเส้น 10 วินาที",
"duration": 10,
"position": 2,
"title": "ตัวอย่างโฆษณาเชิงเส้น"
}
},
"tags": {
"google_0028792773": {
"ad": "0001127859_ad2",
"ad_break_id": "0001127859",
"type": "firstquartile"
}, ...
}
}
-
สำหรับโฆษณาแต่ละรายการ ให้ทริกเกอร์
media_verification_url
โดยเอาค่า ID3 จากการเล่นสื่อโฆษณามาต่อท้ายhttps://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
เหตุการณ์ความคืบหน้า (Progress) มีไว้เพื่อแยกความแตกต่างระหว่างการเล่นภายในและภายนอกช่วงพักโฆษณา และไม่ใช้สำหรับจุดประสงค์อื่นๆ ในการติดตามโฆษณา
คุณระบุเหตุการณ์ความคืบหน้าได้โดยค้นหาไฟล์ JSON ของข้อมูลเมตาเพื่อดูตัวระบุสื่อและยืนยันว่ามีการตั้งค่าฟิลด์ type
เป็น progress
คุณสามารถใช้ Progress ID3 เพื่อทำงานอย่างเช่นการบล็อกส่วนควบคุมวิดีโอ เป็นต้น
ตรวจจับว่าช่วงพักโฆษณาเริ่มต้น/สิ้นสุดตอนไหนในสตรีมโดยใช้ DAI API
DAI จะแทรกข้อมูลเมตา ID3 สําหรับเหตุการณ์ควอร์ไทล์ (เช่น เริ่มต้น ควอร์ไทล์แรก จุดกึ่งกลาง ควอร์ไทล์ที่สาม และสมบูรณ์) ลงในกลุ่มโฆษณาและเหตุการณ์ความคืบหน้า (ทุกๆ 1 วินาที) ในกลุ่มโฆษณาและแถบสเลท เมื่อเห็นแท็ก ID3 ใดๆ แสดงขึ้นมาเป็นครั้งแรก เหตุการณ์ "เริ่มช่วงพักโฆษณา" อาจแสดงขึ้นมา หลังจากนั้น หากไม่พบแท็ก ID3 เหล่านั้นเป็นเวลาประมาณ 2.5 วินาที เหตุการณ์ "สิ้นสุดช่วงพักโฆษณา" ก็จะแสดงขึ้นมา คุณจะรู้ได้ว่าแท็ก ID3 แทรกโดย DAI โดยดูที่คำนำหน้า "google_
" และแท็กอยู่ในไฟล์ JSON ของข้อมูลเมตา
อัปเดตการกำหนดเป้าหมายและ/หรือคีย์-ค่าแบบไดนามิกตามสตรีมของผู้ใช้
คุณเอา session_update_url
ไปแทนที่พารามิเตอร์แท็กโฆษณาทั้งหมดที่ใช้สำหรับคำขอโฆษณาที่กำลังมาใหม่สำหรับสตรีมแบบสด (คล้ายกับ replaceAdTagParameters
) ได้ วิธีนี้มีประโยชน์ในกรณีที่จำเป็นต้องอัปเดตข้อมูลการกำหนดเป้าหมายเป็นรายโปรแกรมและรายผู้ใช้ (เช่น สำหรับการถ่ายทอดกีฬาสดที่อาจไม่ทราบการกำหนดเป้าหมายล่วงหน้า)