Google DAI Pod Serve API ช่วยให้คุณแทรกโฆษณาฝั่งเซิร์ฟเวอร์ที่ขับเคลื่อนโดย Google Ads ไปพร้อมกับควบคุมการต่อวิดีโอของคุณเองได้
คู่มือนี้แสดงวิธีโต้ตอบกับ Pod Feeds API และสร้างฟังก์ชันการทำงานที่คล้ายกันด้วย IMA DAI SDK หากมีคำถามเฉพาะเกี่ยวกับ ฟังก์ชันที่รองรับ โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าของ Google
Pod Serve API รองรับสตรีมการแสดงพ็อดในโปรโตคอลสตรีมมิง HLS หรือ MPEG-DASH คู่มือนี้มุ่งเน้นที่สตรีม HLS และไฮไลต์ความแตกต่างสำคัญระหว่าง HLS และ MPEG-DASH ในบางขั้นตอน
หากต้องการผสานรวม Pod Serve API เข้ากับแอปสำหรับสตรีม VOD ให้ทำตามขั้นตอนต่อไปนี้
ส่งคำขอลงทะเบียนสตรีมไปยัง Ad Manager
ส่งคำขอ POST ไปยังปลายทางการลงทะเบียนสตรีม จากนั้นคุณจะได้รับการตอบกลับ JSON ที่มีรหัสสตรีมเพื่อส่งไปยังเซิร์ฟเวอร์การจัดการไฟล์ Manifest และปลายทาง Pod Serve API ที่เกี่ยวข้อง
ปลายทาง API
POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json
พารามิเตอร์เส้นทาง
{network_code} |
รหัสเครือข่าย Google Ad Manager 360 |
พารามิเตอร์เนื้อหา JSON
targeting_parameters |
ออบเจ็กต์ JSON ที่มีรหัสแหล่งที่มาของเนื้อหา (cmsid), รหัสวิดีโอ (vid) และพารามิเตอร์การกำหนดเป้าหมายของโฆษณา ต้องระบุ |
JSON ของการตอบกลับ
media_verification_url |
URL ฐานที่จะใช้คำสั่ง ping กับเหตุการณ์การติดตามการเล่น URL การยืนยันสื่อที่สมบูรณ์จะสร้างขึ้นโดยการเพิ่มรหัสเหตุการณ์ของโฆษณาต่อท้าย URL พื้นฐานนี้ |
metadata_url |
URL ที่จะขอข้อมูลเมตาของพ็อดโฆษณา |
stream_id |
สตริงที่ใช้ระบุเซสชันของสตรีมปัจจุบัน |
valid_for |
ระยะเวลาที่เหลือจนกว่าเซสชันการสตรีมปัจจุบันจะหมดอายุในรูปแบบ dhms (วัน ชั่วโมง นาที วินาที) เช่น 2h0m0.000s แสดงถึงระยะเวลา 2 ชั่วโมง
|
valid_until |
เวลาที่เซสชันของสตรีมปัจจุบันหมดอายุ โดยเป็นสตริงวันที่และเวลา ISO 8601 ในรูปแบบ yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm
|
ตัวอย่างคำขอ (cURL)
curl -X POST \
-d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration
ตัวอย่างการตอบกลับ
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
ในกรณีที่เกิดข้อผิดพลาด ระบบจะส่งรหัสข้อผิดพลาด HTTP มาตรฐานโดยไม่มีเนื้อหาการตอบสนอง JSON
แยกวิเคราะห์การตอบกลับ JSON และจัดเก็บค่าที่เกี่ยวข้อง
ขอไฟล์ Manifest ของสตรีมจากโปรแกรมจัดการไฟล์ Manifest
เครื่องมือจัดการไฟล์ Manifest แต่ละรายการมีรูปแบบคำขอและคำตอบที่แตกต่างกัน ติดต่อผู้ให้บริการจัดการอุปกรณ์เพื่อทำความเข้าใจข้อกำหนดเฉพาะของผู้ให้บริการ หากคุณใช้โปรแกรมจัดการไฟล์ Manifest ของตนเอง โปรดอ่านคู่มือโปรแกรมจัดการไฟล์ Manifest เพื่อทำความเข้าใจข้อกำหนดของคอมโพเนนต์นี้
โดยทั่วไป คุณต้องส่งรหัสสตรีมที่ส่งโดยปลายทางการลงทะเบียนด้านบนไปยังโปรแกรมจัดการไฟล์ Manifest เพื่อสร้างไฟล์ Manifest เฉพาะเซสชัน การตอบกลับคำขอไฟล์ Manifest จะเป็นสตรีมวิดีโอที่มีทั้งเนื้อหาและโฆษณา เว้นแต่ว่าเครื่องมือจัดการไฟล์ Manifest จะระบุไว้อย่างชัดแจ้ง
ตัวอย่างคำขอ (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
ตัวอย่างการตอบกลับ (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
เล่นสตรีม
โหลดไฟล์ Manifest ที่คุณได้รับจากเซิร์ฟเวอร์การจัดการไฟล์ Manifest ลงในโปรแกรมเล่นวิดีโอและเริ่มเล่น
ขอข้อมูลเมตาของพ็อดโฆษณาจาก Ad Manager
ส่งคำขอ GET
ไปยัง metadata_url
ที่คุณได้รับในขั้นตอนที่ 1 ขั้นตอนนี้ต้องเกิดขึ้นหลังจากที่คุณได้รับไฟล์ Manifest ที่เชื่อมเข้าด้วยกันจากโปรแกรมจัดการไฟล์ Manifest ในทางกลับกัน คุณจะได้รับออบเจ็กต์ JSON ที่มีพารามิเตอร์ต่อไปนี้
tags |
ชุดคู่คีย์-ค่าที่มีเหตุการณ์โฆษณาทั้งหมดที่ปรากฏในสตรีม คีย์คืออักขระ 17 ตัวแรกของรหัสเหตุการณ์โฆษณาที่ปรากฏในข้อมูลเมตาที่ตั้งเวลาของสตรีม หรือในกรณีที่เป็นเหตุการณ์ประเภท progress รหัสเหตุการณ์โฆษณาแบบเต็ม
แต่ละค่าจะเป็นออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้
|
||||||||||||||||||
ads |
ชุดของคู่คีย์-ค่าที่อธิบายโฆษณาทั้งหมดที่ปรากฏในสตรีม คีย์คือรหัสโฆษณาที่ตรงกับค่าที่พบในออบเจ็กต์ tags ที่แสดงด้านบน แต่ละค่าจะเป็นออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้
|
||||||||||||||||||
ad_breaks |
ชุดของคู่คีย์-ค่าที่อธิบายช่วงพักโฆษณาทั้งหมดที่ปรากฏในสตรีม
คีย์คือรหัสช่วงพักโฆษณาที่ตรงกับค่าที่พบในออบเจ็กต์ tags และ ads ที่ระบุไว้ข้างต้น แต่ละค่าจะเป็นออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้
|
เก็บค่าเหล่านี้เพื่อเชื่อมโยงกับเหตุการณ์ข้อมูลเมตาที่กำหนดเวลาภายในสตรีมวิดีโอ
ตัวอย่างคำขอ (cURL)
curl https://dai.google.com/.../metadata
ตัวอย่างการตอบกลับ
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
ฟังเหตุการณ์โฆษณา
ฟังข้อมูลเมตาที่กำหนดเวลาผ่านเหตุการณ์โฆษณาที่ทริกเกอร์ในสตรีมเสียง/วิดีโอของโปรแกรมเล่นวิดีโอ
สำหรับสตรีม MPEG-TS ข้อมูลเมตาจะปรากฏเป็นแท็ก ID3 v2.3 ในย่านความถี่ แท็กข้อมูลเมตาแต่ละรายการจะมีรหัส TXXX
และค่าจะขึ้นต้นด้วยสตริง google_
ตามด้วยชุดอักขระ ค่านี้คือรหัสเหตุการณ์โฆษณา
XXX
ใน TXXX
ไม่ใช่ตัวยึดตำแหน่ง สตริง TXXX
คือรหัสแท็ก ID3 ที่สงวนไว้สำหรับ "ข้อความที่กำหนดโดยผู้ใช้"
ตัวอย่างแท็ก ID3
TXXXgoogle_1234567890123456789
สำหรับสตรีม MP4 ระบบจะส่งเหตุการณ์เหล่านี้ในรูปแบบอีเมลในกลุ่มที่จำลองแท็ก ID3 v2.3 กล่องข้อความอิเล็กทรอนิกส์ที่เกี่ยวข้องแต่ละกล่องจะมีค่า scheme_id_uri
เป็น https://aomedia.org/emsg/ID3
หรือ https://developer.apple.com/streaming/emsg-id3
และค่า message_data
ที่เริ่มต้นด้วย ID3TXXXgoogle_
ค่า message_data
ที่ไม่มีคำนำหน้า ID3TXXX
คือรหัสเหตุการณ์โฆษณา
ตัวอย่างกล่องข้อความอิเล็กทรอนิกส์
โครงสร้างข้อมูลอาจแตกต่างกันไป ขึ้นอยู่กับไลบรารีโปรแกรมเล่นสื่อของคุณ
หากรหัสเหตุการณ์โฆษณาคือ google_1234567890123456789
คำตอบจะมีลักษณะดังนี้
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
ไลบรารีโปรแกรมเล่นสื่อบางแห่งจะแสดงเหตุการณ์อีเมลโดยอัตโนมัติที่จำลองแท็ก ID3 เป็นแท็ก ID3 แบบเนทีฟ ในกรณีนี้ สตรีม MP4 จะแสดงแท็ก ID3 ที่เหมือนกันเป็น MPEG_TS
อัปเดต UI ของแอปโปรแกรมเล่นวิดีโอของไคลเอ็นต์
รหัสเหตุการณ์โฆษณาแต่ละรหัสจะจับคู่กับคีย์ในออบเจ็กต์ tags
จากขั้นตอนที่ 4 ได้
การจับคู่ค่าเหล่านี้มี 2 ขั้นตอนดังนี้
ตรวจหาคีย์ที่ตรงกับรหัสเหตุการณ์โฆษณาทั้งหมดในออบเจ็กต์
tags
หากพบรายการที่ตรงกัน ให้ดึงข้อมูลประเภทเหตุการณ์และออบเจ็กต์ad
และad_break
ที่เกี่ยวข้อง เหตุการณ์เหล่านี้ควรมีประเภทprogress
หากไม่พบรหัสเหตุการณ์โฆษณาทั้งหมดที่ตรงกัน ให้ตรวจสอบออบเจ็กต์
tags
เพื่อหาคีย์ที่ตรงกับอักขระ 17 ตัวแรกของรหัสเหตุการณ์โฆษณา ดึงข้อมูลประเภทเหตุการณ์และออบเจ็กต์ad
และad_break
ที่เกี่ยวข้อง การดำเนินการนี้ควรเรียกเหตุการณ์ทั้งหมดที่มีประเภทนอกเหนือจากprogress
ใช้ข้อมูลที่ดึงมานี้เพื่ออัปเดต UI ของโปรแกรมเล่น ตัวอย่างเช่น เมื่อคุณได้รับ
start
หรือเหตุการณ์progress
แรก ให้ซ่อนตัวควบคุมการค้นหาของโปรแกรมเล่นและแสดงโฆษณาซ้อนทับที่อธิบายตำแหน่งของโฆษณาปัจจุบันในช่วงพักโฆษณา เช่น "โฆษณา 1 จาก 3"
ตัวอย่างรหัสเหตุการณ์โฆษณา
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
ตัวอย่างออบเจ็กต์แท็ก
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
ส่งคำสั่ง ping ของการยืนยันสื่อ
ต้องส่งคำสั่ง ping การยืนยันสื่อไปยัง Ad Manager ทุกครั้งที่ได้รับเหตุการณ์โฆษณาประเภทอื่นที่ไม่ใช่ progress
หากต้องการสร้าง URL การยืนยันสื่อที่สมบูรณ์ของเหตุการณ์โฆษณา ให้ใส่รหัสเหตุการณ์ของโฆษณาแบบเต็มต่อท้ายค่า media_verification_url
จากการตอบกลับการลงทะเบียนสตรีม
สร้างคำขอ GET โดยใช้ URL แบบเต็ม หากคำขอการยืนยันสำเร็จแล้ว คุณจะได้รับการตอบกลับ HTTP พร้อมรหัสสถานะ 202
ไม่เช่นนั้น ระบบจะแสดงรหัสข้อผิดพลาด HTTP 404
ตัวอย่างคำขอ (cURL)
curl https://{...}/media/google_5555555555123456789
ตัวอย่างการตอบกลับที่ประสบความสำเร็จ
HTTP/1.1 202 Accepted