คู่มือนี้ครอบคลุมการพัฒนาแอปพลิเคชันไคลเอ็นต์เพื่อโหลดไลฟ์สด HLS หรือ DASH ด้วย Pod Serving API และตัวจัดการไฟล์ Manifest
ข้อกำหนดเบื้องต้น
คุณต้องมีสิ่งต่อไปนี้ก่อนดำเนินการต่อ
คีย์ชิ้นงานที่กำหนดเองสำหรับกิจกรรมไลฟ์สดที่กำหนดค่าด้วยประเภท DAI
Pod serving redirectหากต้องการรับคีย์นี้ ให้ทำตามขั้นตอนต่อไปนี้ใช้ไลบรารีของไคลเอ็นต์ SOAP API เพื่อเรียกใช้เมธอด
LiveStreamEventService.createLiveStreamEventsด้วยออบเจ็กต์LiveStreamEventและตั้งค่าพร็อพเพอร์ตี้dynamicAdInsertionTypeเป็นค่า enumPOD_SERVING_REDIRECTดูไลบรารีของไคลเอ็นต์ทั้งหมดได้ที่ไลบรารีของไคลเอ็นต์และโค้ดตัวอย่าง
ตรวจสอบว่า SDK โฆษณาสื่ออินเทอร์แอกทีฟ (IMA) พร้อมใช้งานสำหรับแพลตฟอร์มของคุณหรือไม่ เราขอแนะนำให้ใช้ IMA SDK เพื่อเพิ่มรายได้ โปรดดูรายละเอียดที่หัวข้อตั้งค่า IMA SDK สำหรับ DAI
ส่งคำขอสตรีม
เมื่อผู้ใช้เลือกไลฟ์สด ให้ทำดังนี้
ส่งคำขอ
POSTไปยังเมธอดบริการไลฟ์สด โปรดดูรายละเอียดที่หัวข้อเมธอด: streamส่งพารามิเตอร์การกำหนดเป้าหมายโฆษณาในรูปแบบ
application/x-www-form-urlencodedหรือapplication/jsonคำขอนี้จะลงทะเบียนเซสชันสตรีมกับ DAI ของ Googleตัวอย่างต่อไปนี้จะสร้างคำขอสตรีม
การเข้ารหัสแบบฟอร์ม
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const params = new URLSearchParams({ cust_params: 'section=sports&page=golf,tennis' }).toString(); const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); console.log(await response.json());การเข้ารหัส JSON
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cust_params: { section: 'sports', page: 'golf,tennis' } }) }); console.log(await response.json());หากสําเร็จ คุณจะเห็นเอาต์พุตที่คล้ายกับต่อไปนี้
{ "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS", "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/", "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata", "session_update_url": "https://dai.google.com/linear/.../session", "polling_frequency": 10 }ในคำตอบ JSON ให้ค้นหารหัสเซสชันของสตรีมและจัดเก็บข้อมูลอื่นๆ สำหรับขั้นตอนถัดไป
ข้อมูลเมตาของโฆษณาแบบสำรวจ
หากต้องการสำรวจข้อมูลเมตาของโฆษณา ให้ทำดังนี้
อ่านค่า
metadata_urlจากการตอบกลับการลงทะเบียนสตรีมส่งคำขอ
GETเริ่มต้นไปยังปลายทางmetadata_url- ละเว้นพารามิเตอร์การค้นหา
delta_tokenกระบวนการนี้ช่วยให้เซิร์ฟเวอร์แสดงข้อมูลเมตาแบบเต็มสำหรับช่วงที่บันทึกวิดีโอดิจิทัล (DVR) ของสตรีม ช่วงที่บันทึกด้วย DVR จะมีกรอบเวลาของการออกอากาศที่ผู้ชมสามารถกรอกลับและเล่นได้ การตอบกลับมีช่องnext_delta_token
- ละเว้นพารามิเตอร์การค้นหา
หากต้องการเพิ่มประสิทธิภาพแบนด์วิดท์ ให้จัดเก็บค่า
next_delta_tokenจากการตอบกลับล่าสุดในคำขอถัดไป ให้ส่งค่าดังกล่าวเป็นพารามิเตอร์การค้นหา
delta_tokenเซิร์ฟเวอร์จะแสดงเฉพาะข้อมูลเมตาที่มีการเปลี่ยนแปลงนับตั้งแต่สร้างโทเค็นนั้นขึ้นมา ส่งโทเค็นล่าสุดที่คุณได้รับเสมอ อย่าพยายามแยกวิเคราะห์ แก้ไข หรือสร้างโทเค็น โปรดดูรายละเอียดที่หัวข้อเมธอด: ข้อมูลเมตาตัวอย่างต่อไปนี้จะดึงข้อมูลเมตาของโฆษณา
// Initial request (returns full metadata and next_delta_token) let response = await fetch(metadata_url); let metadata = await response.json(); let deltaToken = metadata.next_delta_token; // Subsequent request (returns only changes since deltaToken) if (deltaToken) { const url = new URL(metadata_url); url.searchParams.append('delta_token', deltaToken); response = await fetch(url.toString()); const deltaMetadata = await response.json(); // Merge deltaMetadata into your local cache mergeMetadata(metadata, deltaMetadata); deltaToken = deltaMetadata.next_delta_token; }หากทำสำเร็จ คุณจะได้รับการตอบกลับ PodMetadata หากคุณระบุพารามิเตอร์
delta_tokenการตอบกลับจะมีเฉพาะโฆษณา ช่วงพักโฆษณา และแท็กที่เซิร์ฟเวอร์เพิ่มหรืออัปเดตตั้งแต่เซิร์ฟเวอร์สร้างโทเค็น การตอบกลับยังมีค่าnext_delta_tokenใหม่ด้วย หากช่วงพักโฆษณาใดล้าสมัย การตอบกลับจะมีรายการobsolete_ad_break_idsของช่วงพักโฆษณาที่จะนำออกจากแคชด้วย{ "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0", "obsolete_ad_break_ids": ["0003069407"], "tags":{ "google_1022389921":{ "ad":"0003069408_ad1", "ad_break_id":"0003069408", "type":"start" }, ... }, "ads":{ "0003069408_ad1":{ "ad_break_id":"0003069408", "position":1, "duration":10.01, "title":"External - Pod Midroll 1", "clickthrough_url":"https://.../", ... }, ... }, "ad_breaks":{ "0003069408":{ "type":"mid", "duration":30, "ads":3 }, ... } }บันทึกออบเจ็กต์
tagsและผสานการอัปเดตลงในแคชในเครื่อง หากมีพารามิเตอร์obsolete_ad_break_idsให้นำช่วงพักโฆษณาเหล่านั้น รวมถึงโฆษณาและแท็กที่เกี่ยวข้องออกจากแคชตั้งค่าตัวจับเวลาโดยใช้ค่า
polling_frequencyเพื่อขอข้อมูลเมตาเป็นประจำ ในการสำรวจแต่ละครั้ง ให้ส่งค่าnext_delta_tokenที่แสดงผลในการตอบกลับข้อมูลเมตาล่าสุดเป็นพารามิเตอร์การค้นหาdelta_token
โหลดไลฟ์สดลงในวิดีโอเพลเยอร์
หลังจากได้รับรหัสเซสชันจากการตอบกลับการลงทะเบียนแล้ว ให้ส่งรหัสดังกล่าวไปยังตัวจัดการไฟล์ Manifest หรือสร้าง URL ของไฟล์ Manifest เพื่อโหลดสตรีมลงในวิดีโอเพลเยอร์
หากต้องการส่งรหัสเซสชัน โปรดดูเอกสารประกอบเกี่ยวกับตัวจัดการไฟล์ Manifest หากคุณพัฒนาตัวจัดการไฟล์ Manifest โปรดดูตัวจัดการไฟล์ Manifest สำหรับไลฟ์สด
ตัวอย่างต่อไปนี้จะประกอบ URL ของไฟล์ Manifest
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
เมื่อโปรแกรมเล่นพร้อมแล้ว ให้เริ่มเล่น
รอเหตุการณ์โฆษณา
ตรวจสอบรูปแบบคอนเทนเนอร์ของไลฟ์สดเพื่อหาข้อมูลเมตาที่กำหนดเวลาไว้ ดังนี้
สตรีม HLS ที่มีคอนเทนเนอร์ Transport Stream (TS) จะใช้แท็ก ID3 ที่กำหนดเวลาเพื่อส่งข้อมูลเมตาที่กำหนดเวลา โปรดดูรายละเอียดที่หัวข้อเกี่ยวกับ Common Media Application Format ที่มี HTTP Live Streaming (HLS)
สตรีม DASH ใช้องค์ประกอบ
EventStreamเพื่อระบุเหตุการณ์ในไฟล์ Manifestสตรีม DASH จะใช้องค์ประกอบ
InbandEventStreamเมื่อกลุ่มมีกล่องข้อความเหตุการณ์ (emsg) สำหรับข้อมูลเพย์โหลด ซึ่งรวมถึงแท็ก ID3 ดูรายละเอียดได้ที่ InbandEventStreamสตรีม CMAF ซึ่งรวมถึง DASH และ HLS จะใช้กล่อง
emsgที่มีแท็ก ID3
หากต้องการดึงข้อมูลแท็ก ID3 จากสตรีม โปรดดูคำแนะนำของวิดีโอเพลเยอร์ ดูรายละเอียดได้ที่คู่มือการจัดการข้อมูลเมตาที่กำหนดเวลา
หากต้องการดึงรหัสเหตุการณ์โฆษณาจากแท็ก ID3 ให้ทำดังนี้
- กรองเหตุการณ์ตาม
scheme_id_uriด้วยurn:google:dai:2018หรือhttps://aomedia.org/emsg/ID3 ดึงข้อมูลอาร์เรย์ไบต์จากช่อง
message_dataตัวอย่างต่อไปนี้จะถอดรหัสข้อมูล
emsgเป็น JSON{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }กรองแท็ก ID3 ด้วยรูปแบบ
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
แสดงข้อมูลเหตุการณ์โฆษณา
หากต้องการค้นหาออบเจ็กต์ TagSegment ให้ทำดังนี้
ดึงข้อมูลเมตาของโฆษณา
tagsออบเจ็กต์จากข้อมูลเมตาของโฆษณาแบบสำรวจ ออบเจ็กต์tagsคืออาร์เรย์ของออบเจ็กต์TagSegmentใช้รหัสเหตุการณ์โฆษณาแบบเต็มเพื่อค้นหาออบเจ็กต์
TagSegmentที่มีประเภทprogressใช้อักขระ 17 ตัวแรกของรหัสเหตุการณ์โฆษณาเพื่อค้นหาออบเจ็กต์
TagSegmentประเภทอื่นๆเนื่องจากแอปไคลเอ็นต์ทำการสำรวจข้อมูลเมตาของโฆษณาเป็นระยะๆ จึงอาจเกิดความล่าช้าระหว่างเวลาที่วิดีโอเพลเยอร์พบแท็ก ID3 ในสตรีมและเวลาที่ข้อมูลเมตาที่เกี่ยวข้องพร้อมใช้งาน หากแอปไคลเอ็นต์ไม่พบแท็ก ID3 ในแท็กที่จัดเก็บไว้ ให้เก็บแท็กไว้ในคิวและประมวลผลแท็กอีกครั้งหลังจากการสำรวจข้อมูลเมตาครั้งถัดไป เก็บแท็กไว้ในคิวจนกว่าการประมวลผลจะเสร็จสิ้น
หลังจากมี
TagSegmentแล้ว ให้ใช้พร็อพเพอร์ตี้ad_break_idเป็นคีย์เพื่อค้นหาออบเจ็กต์AdBreakในออบเจ็กต์ad_breaksของข้อมูลเมตาโฆษณาตัวอย่างต่อไปนี้จะค้นหาออบเจ็กต์
AdBreak{ "type":"mid", "duration":15, "ads":1 }ใช้ข้อมูล
TagSegmentและAdBreakเพื่อแสดงข้อมูลเกี่ยวกับตำแหน่งโฆษณาในช่วงพักโฆษณา เช่นAd 1 of 3
ส่ง ping ยืนยันสื่อ
ส่ง ping ยืนยันสื่อสำหรับเหตุการณ์โฆษณาทุกรายการ ยกเว้นประเภท progress
Google DAI จะทิ้งเหตุการณ์ progress และการส่งเหตุการณ์เหล่านี้บ่อยครั้งอาจส่งผลต่อประสิทธิภาพของแอป
หากต้องการสร้าง URL การยืนยันสื่อที่สมบูรณ์ของเหตุการณ์โฆษณา ให้ทำดังนี้
จากการตอบกลับสตรีม ให้เพิ่มรหัสเหตุการณ์โฆษณาแบบเต็มต่อท้ายค่า
media_verification_urlส่งคำขอ
GETด้วย URL แบบเต็ม:// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);หากทำสำเร็จ คุณจะได้รับการตอบกลับสถานะโค้ด
202มิฉะนั้น คุณจะได้รับรหัสข้อผิดพลาด404
คุณสามารถใช้เครื่องมือตรวจสอบกิจกรรมการสตรีม (SAM) เพื่อตรวจสอบบันทึกประวัติของเหตุการณ์โฆษณาทั้งหมดได้ โปรดดูรายละเอียดที่หัวข้อตรวจสอบและแก้ปัญหาไลฟ์สด