این راهنما توسعه برنامه کارخواه را برای بار کردن جاریسازی زنده HLS یا DASH با میانای برنامهسازی کاربردی Pod serving و دستکاریکننده مانیفست شما پوشش میدهد.
پیشنیازها
پیشاز ادامه دادن، باید موارد زیر را داشته باشید:
کلید دارایی سفارشی برای رویداد جاریسازی زنده که با نوع
Pod serving redirectDAI پیکربندی شده است. برای دریافت این کلید، این مراحل را دنبال کنید:از کتابخانه کارخواه SOAP API برای فراخوانی روش
LiveStreamEventService.createLiveStreamEventsبا شیءLiveStreamEventو ویژگیdynamicAdInsertionTypeتنظیمشده روی مقدار شمارشیPOD_SERVING_REDIRECTاستفاده کنید. برای همه کتابخانههای کارخواه، به کتابخانههای کارخواه و کد نمونه مراجعه کنید.
بررسی کنید که آیا کیت توسعه نرمافزار آگهیهای رسانهای تعاملی (IMA) برای پلاتفرم شما دردسترس است یا نه. توصیه میکنیم برای افزایش درآمد از «کیت توسعه نرمافزار آگهیهای رسانهای تعاملی» استفاده کنید. برای جزئیات، راهاندازی IMA SDK برای DAI را ببینید.
درخواست جاریسازی
وقتی کاربرتان جاریسازی را انتخاب میکند، کارهای زیر را انجام دهید:
درخواست
POSTبه روش سرویس جاریسازی زنده ارسال کنید. برای جزئیات، روش: جاریسازی را ببینید.پارامترهای هدفیابی آگهی را در قالبهای
application/x-www-form-urlencodedیاapplication/jsonارسال کنید. این درخواست یک جلسه جاریسازی را با Google DAI ثبت میکند.مثال زیر درخواست جاریسازی را نشان میدهد:
کدبندی فرم
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ارسال کنید.
جاریسازی را در پخشکننده ویدیو بار کنید
پساز دریافت شناسه جلسه از پاسخ ثبتنام، شناسه را به دستکاریکننده مانیفست خود ارسال کنید یا یک نشانی وب مانیفست بسازید تا جاریسازی را در پخشکننده ویدیو بارگیری کنید.
برای ارسال شناسه جلسه، به اسناد دستکاریکننده مانیفست خود مراجعه کنید. اگر دستکاریکننده مانیفست توسعه میدهید، دستکاریکننده مانیفست برای جاریسازی زنده را ببینید.
مثال زیر نشانی وب مانیفست را مونتاژ میکند:
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 زمانبندیشده برای حمل فراداده زمانبندیشده استفاده میکنند. برای جزئیات، درباره قالب برنامه رسانه مشترک با جاریسازی زنده اچتیتیپی (HLS) را ببینید.
جاریسازیهای DASH از عناصر
EventStreamبرای مشخص کردن رویدادها در مانیفست استفاده میکنند.جاریسازیهای 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استفاده کنید.از ۱۷ نویسه اول شناسه رویداد آگهی برای پیدا کردن شیء
TagSegmentاز انواع دیگر استفاده کنید.چون برنامه کارخواه شما فرادادههای آگهی را بهطور دورهای نظرسنجی میکند، ممکن است بین زمانی که پخشکننده ویدیو شما با برچسب ID3 در جاریسازی مواجه میشود و زمانی که فرادادههای مرتبط دردسترس قرار میگیرند، تأخیری رخ دهد. اگر برنامه کارخواه شما برچسب ID3 را در برچسبهای ذخیرهشده پیدا نکرد، برچسب را در صف نگه دارید و پساز نظرسنجی فراداده بعدی، برچسب را دوباره پردازش کنید. برچسب را تا پایان پردازش در صف نگه دارید.
پساز دریافت
TagSegment، از ویژگیad_break_idبهعنوان کلید برای پیدا کردن شیءAdBreakدر شیء فراداده آگهیad_breaksاستفاده کنید.مثال زیر شیء
AdBreakرا پیدا میکند:{ "type":"mid", "duration":15, "ads":1 }از دادههای
TagSegmentوAdBreakبرای نمایش اطلاعات مربوط به جایگاه آگهی در وقفه آگهی استفاده کنید. بهعنوان مثال،Ad 1 of 3.
ارسال پینگهای درستیسنجی رسانه
برای هر رویداد آگهی، بهجز نوع progress، پینگ درستیسنجی رسانه ارسال کنید.
Google DAI رویدادهای progress را نادیده میگیرد و ارسال مکرر این رویدادها ممکن است
بر عملکرد برنامهتان تأثیر بگذارد.
برای تولید نشانی وب کامل درستیسنجی رسانه برای رویداد آگهی، کارهای زیر را انجام دهید:
از پاسخ جاریسازی، شناسه کامل رویداد آگهی را به مقدار
media_verification_urlاضافه کنید.درخواست
GETرا با نشانی وب کامل ایجاد کنید:// 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) برای بررسی گزارش سابقه همه رویدادهای آگهی استفاده کنید. برای جزئیات، به پایش و عیبیابی جاریسازی زنده مراجعه کنید.