تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لإدراج الإعلانات الديناميكي في "إعلانات الوسائط التفاعلية"، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني والفيديو الخاص بالمحتوى داخل تطبيقك.
اختيار حلّ "الإعلانات الديناميكية أثناء عرض الفيديو" الذي يهمّك
بث مباشر للمباريات المسجّلة باستخدام Google Cloud Video Stitcher API
يوضّح هذا الدليل كيفية استخدام حزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات الوسائط التفاعلية" (IMA) لدمج الإعلانات الديناميكية (DAI) في HTML5 من أجل طلب بث مباشر وتشغيله لحدث مسجّل باستخدام Google Cloud Video Stitcher API، وكيفية إدراج فاصل إعلاني أثناء التشغيل.
يتوسّع هذا الدليل في المثال الأساسي الوارد في دليل البدء الخاص بـ "إعلانات الوسائط التفاعلية" الديناميكية.
للحصول على معلومات حول الدمج مع منصات أخرى أو استخدام حِزم تطوير البرامج لإعلانات الوسائط التفاعلية من جهة العميل، يُرجى الاطّلاع على حِزم تطوير البرامج لإعلانات الوسائط التفاعلية.
لعرض عملية تكامل نموذجية مكتملة أو اتّباعها، نزِّل مثالاً على أداة دمج الفيديوهات في السحابة الإلكترونية بتنسيق HLS أو DASH.
إعداد مشروع على Google Cloud
إعداد مشروع على Google Cloud وإعداد حسابات الخدمة للوصول إلى المشروع
أنشئ إعدادًا لحدث بث مباشر باستخدام البث المباشر الخاص بك أو بث مباشر تجريبي. يفترض هذا الدليل أنّك تستخدم بثًا مباشرًا وفق بروتوكول HTTP (HLS).
أدخِل المتغيّرات التالية لاستخدامها في حزمة تطوير البرامج لإعلانات الوسائط التفاعلية:- الموقع الجغرافي
- منطقة Google Cloud
التي تم إنشاء الإعدادات النشطة فيها:
LOCATION - رقم المشروع
- رقم مشروع Google Cloud المستخدَم في Video Stitcher API:
PROJECT_NUMBER - رمز OAuth المميز
رمز مميز قصير الأمد لبروتوكول OAuth خاص بحساب خدمة يتضمّن دور مستخدم Video Stitcher:
OAUTH_TOKEN
مزيد من المعلومات حول إنشاء بيانات اعتماد قصيرة الأمد لحسابات الخدمة يمكن إعادة استخدام رمز OAuth المميز في طلبات متعددة ما دام لم تنتهِ صلاحيته.
- رمز الشبكة
رمز شبكة "مدير الإعلانات" لطلب الإعلانات:
NETWORK_CODE
- رقم تعريف الإعدادات المباشرة
- معرّف الإعدادات المباشرة الذي حدّدته عند إنشاء حدث البث المباشر:
LIVE_CONFIG_ID - مفتاح مادة العرض المخصّصة
- مفتاح العنصر المخصّص في "مدير إعلانات Google" الذي تم إنشاؤه أثناء عملية إنشاء إعدادات لحدث بث مباشر باستخدام Video Stitcher API:
CUSTOM_ASSET_KEY
ضبط بيئة تطوير
تعرض تطبيقات IMA النموذجية طلبات بث HLS فقط. سيظل بإمكانك استخدام بث DASH عند إنشاء الفئة VideoStitcherLiveStreamRequest. عند إعداد مشغّل متوافق مع DASH، عليك إعداد أداة معالجة لأحداث تقدّم مشغّل الفيديو يمكنها توفير البيانات الوصفية للفيديو إلى StreamManager.processMetadata().
تتلقّى هذه الدالة ثلاث مَعلمات:
type: سلسلة يجب ضبطها على'ID3'لبث HLS و'urn:google:dai:2018'لبث DASH.
data: بالنسبة إلى رسائل أحداث DASH، هذا هو سلسلة بيانات الرسالة.
timestamp: رقم يمثّل وقت بدء رسالة الحدث لعمليات بث DASH.
أرسِل البيانات الوصفية في أقرب وقت ممكن وبأسرع ما يمكن أن توفّره أحداث اللاعبين. إذا كانت البيانات الوصفية مفقودة أو غير صحيحة، قد لا تؤدي حزمة تطوير البرامج لواجهة IMA DAI إلى تشغيل أحداث الإعلانات، ما يؤدي إلى عدم الإبلاغ عن أحداث الإعلانات بشكل صحيح.
نزِّل أمثلة على "إعلانات الوسائط التفاعلية" (IMA) في "إعلانات البث المباشر" (DAI) بتنسيق HTML5 واستخرِج عيّنة HLS.js البسيطة إلى مجلد جديد. هذا المثال هو تطبيق ويب يمكنك استضافته محليًا لأغراض الاختبار.
لاستضافة المثال محليًا، انتقِل إلى المجلد الجديد، ونفِّذ أمر Python التالي لبدء خادم ويب:
python3 -m http.server 8000لا تتوفّر http.server إلا في Python 3.x. يمكنك استخدام أي خادم ويب آخر، مثل خادم Apache HTTP أو Node JS.
افتح متصفّح ويب وانتقِل إلى localhost:8000 للاطّلاع على مشغّل فيديو.
يجب أن يتوافق المتصفّح مع مكتبة HLS.js.
إذا كان كل شيء يعمل بشكل صحيح، سيؤدي النقر على زر التشغيل في مشغّل الفيديو إلى بدء الفيلم القصير "Tears of Steel" بعد عرض إعلان قصير. يتم عرض هذا المحتوى باستخدام بث فيديو عند الطلب (VOD).
طلب بث مباشر
لاستبدال عيّنة بث الفيديو عند الطلب ببثك المباشر، استخدِم فئة
VideoStitcherLiveStreamRequest
التي تنشئ تلقائيًا جلسة إعلانية باستخدام "مدير إعلانات Google". يمكنك استخدام واجهة مستخدم "مدير إعلانات Google" من أجل تحديد موقع جلسات "الإعلانات الديناميكية أثناء عرض الفيديو" التي تم إنشاؤها بغرض المراقبة وتصحيح الأخطاء.
في النموذج الحالي، تتوفّر دوال لطلب بث فيديو عند الطلب أو بث مباشر. لإتاحة استخدامها مع Google Cloud Video Stitcher API، عليك إضافة دالة جديدة لعرض كائن VideoStitcherLiveStreamRequest.
وفي ما يلي مثال لذلك:
// StreamManager which will be used to request ad-enabled streams.
let streamManager;
...
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(
videoElement,
adUiElement
);
streamManager.addEventListener(
[
google.ima.dai.api.StreamEvent.Type.LOADED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
],
onStreamEvent, false);
hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
if (streamManager && data) {
// For each ID3 tag in our metadata, we pass in the type - ID3, the
// tag data (a byte array), and the presentation timestamp (PTS).
data.samples.forEach(function(sample) {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
videoElement.addEventListener('pause', () => {
playButton.style.display = 'block';
});
playButton.addEventListener('click', initiatePlayback);
}
function initiatePlayback() {
requestVideoStitcherStream();
playButton.style.display = "none";
playButton.removeEventListener('click', initiatePlayback);
playButton.addEventListener('click', resumePlayback);
}
...
function requestVideoStitcherStream() {
const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
streamRequest.region = 'LOCATION';
streamRequest.projectNumber = 'PROJECT_NUMBER';
streamRequest.oAuthToken = 'OAUTH_TOKEN';
streamRequest.networkCode = 'NETWORK_CODE';
streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';
streamManager.requestStream(streamRequest);
}
لإجراء اختبار محلي، إذا كانت ملفات البث المباشر مخزّنة في حزمة Cloud Storage، عليك تفعيل
سياسة مشاركة الموارد المتعددة المصادر (CORS) للمصدر
http://localhost:8000.
إعادة تحميل الصفحة بعد ذلك، يمكنك طلب بث مباشر مخصّص وتشغيله.
(اختياري) إضافة خيارات جلسة البث
يمكنك تخصيص طلب البث من خلال إضافة خيارات الجلسة لتجاوز الإعداد التلقائي لواجهة برمجة التطبيقات Cloud Video Stitcher باستخدام VideoStitcherLiveStreamRequest.videoStitcherSessionOptions.
في حال تقديم خيار غير معروف، ستردّ واجهة برمجة التطبيقات Cloud Video Stitcher API برسالة خطأ HTTP 400. يُرجى الرجوع إلى
دليل تحديد المشاكل وحلّها
للحصول على المساعدة.
على سبيل المثال، يمكنك تجاهل خيارات ملف البيان باستخدام مقتطف الرمز التالي الذي يطلب ملفَي بيان بث مباشر مع عرضَين مرتبَين من أدنى معدّل نقل بيانات إلى أعلى معدّل.
...
// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
"manifestOptions": {
"bitrateOrder": "ascending"
}
};
streamManager.requestStream(streamRequest);
إدراج فاصل إعلاني
تُدرج واجهة برمجة التطبيقات Google Cloud Video Stitcher الإعلانات التي يتم استردادها من علامة الإعلان لكل فاصل إعلاني. يتم الإشارة إلى فواصل الإعلانات في ملف البيان باستخدام علامات الإعلانات. يتم إدراج علامات الإعلانات من خلال برنامج ترميز البث المباشر.
إذا كنت تستخدم بثًا مباشرًا خاصًا بك، عليك إدراج علامة الإعلان. لمزيد من المعلومات عن علامات الإعلانات المتوافقة مع HLS وDASH، راجِع مستندات علامات الإعلانات.
إذا أنشأت بثًا مباشرًا باستخدام Google Cloud Livestream API، أدرِج حدث قناة لفاصل إعلاني.
يتم تشغيل الإعلان فور إدراج الفاصل الإعلاني.
تَنظيم
بعد أن استضفت بنجاح بثًا مباشرًا باستخدام واجهة برمجة التطبيقات Google Cloud Video Stitcher وطلبتها باستخدام حزمة تطوير البرامج IMA DAI لـ HTML5، من المهم تنظيف أي موارد عرض.
اتّبِع دليل تنظيف البث المباشر لإزالة أي موارد ومواد عرض غير ضرورية.
أخيرًا، في نافذة الوحدة الطرفية التي بدأت فيها خادم الويب Python 3، استخدِم الأمر ctrl+C لإنهاء الخادم المحلي.