تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج (SDK) لإدراج الإعلانات الديناميكي (DAI) في "إعلانات الوسائط التفاعلية" (IMA)، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب (VOD) أو محتوى مباشر. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني وفيديو المحتوى داخل تطبيقك.
اختيار حلّ "الإعلانات الديناميكية داخل الفيديو" الذي يهمّك
تشغيل فيديوهات عند الطلب مسجّلة باستخدام Google Cloud Video Stitcher API
يوضّح هذا الدليل كيفية استخدام حزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات الوسائط التفاعلية" (IMA) لخدمة "الإعلانات الديناميكية أثناء عرض الفيديو" (DAI) في HTML5 من أجل طلب جلسة بث فيديو عند الطلب (VOD) من Google Cloud وتشغيلها.
يتوسّع هذا الدليل في المثال الأساسي من دليل البدء الخاص بـ IMA DAI.
للحصول على معلومات حول الدمج مع منصات أخرى أو استخدام حِزم تطوير البرامج (SDK) من جهة العميل في "إعلانات الوسائط التفاعلية"، يُرجى الاطّلاع على حِزم تطوير البرامج لإعلانات الوسائط التفاعلية.
للاطّلاع على مثال مكتمل لعملية تكامل أو اتّباع خطواتها، نزِّل مثالاً على أداة دمج الفيديوهات على السحابة الإلكترونية بتنسيق HLS أو DASH.
إعداد مشروع على Google Cloud
إعداد مشروع على Google Cloud وإعداد حسابات الخدمة للوصول إلى المشروع
أدخِل المتغيّرات التالية لاستخدامها في "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية":- الموقع الجغرافي
- منطقة Google Cloud
التي تم فيها إنشاء إعدادات الفيديو عند الطلب:
LOCATION - رقم المشروع
- رقم مشروع Google Cloud الذي يستخدم Video Stitcher API:
PROJECT_NUMBER - الرمز المميز لبروتوكول OAuth
رمز مميز قصير الأمد لبروتوكول OAuth خاص بحساب خدمة يتضمّن دور مستخدم Video Stitcher:
OAUTH_TOKEN
مزيد من المعلومات حول إنشاء رموز مميّزة قصيرة الأمد لبروتوكول OAuth يمكن إعادة استخدام الرمز المميز OAuth في طلبات متعددة ما دام لم تنتهِ صلاحيته.
- رمز الشبكة
معرِّف شبكة "إدارة الإعلانات" لطلب الإعلانات:
NETWORK_CODE
- رقم تعريف إعداد الفيديو عند الطلب
معرّف إعدادات الفيديو عند الطلب (VOD) لتدفق الفيديو عند الطلب:
VOD_CONFIG_IDيمكنك الاطّلاع على مزيد من المعلومات حول إنشاء معرّف إعدادات الفيديو عند الطلب في دليل إنشاء إعدادات الفيديو عند الطلب في Cloud Stitching.
ضبط بيئة تطوير
تعرض تطبيقات IMA النموذجية طلبات بث HLS فقط. سيظل بإمكانك استخدام بث DASH عند إنشاء الفئة VideoStitcherVodStreamRequest. عند إعداد مشغّل متوافق مع DASH، عليك إعداد أداة معالجة لأحداث تقدّم مشغّل الفيديو يمكنها توفير البيانات الوصفية للفيديو إلى StreamManager.processMetadata().
تتلقّى هذه الدالة ثلاث مَعلمات:
type: سلسلة يجب ضبطها على'ID3'لبث HLS و'urn:google:dai:2018'لبث DASH.
data: بالنسبة إلى رسائل أحداث DASH، هذا هو سلسلة بيانات الرسالة.
timestamp: رقم يمثّل وقت بدء رسالة الحدث لعمليات بث DASH.
أرسِل البيانات الوصفية في أقرب وقت ممكن وبأسرع ما يمكن أن توفّره أحداث اللاعبين. إذا كانت البيانات الوصفية مفقودة أو غير صحيحة، قد لا تؤدي حزمة تطوير البرامج لواجهة IMA DAI إلى تشغيل أحداث الإعلانات، ما يؤدي إلى عدم الإبلاغ عن أحداث الإعلانات بشكل صحيح.
نزِّل أمثلة IMA DAI لـ HTML5 واستخرِج ملف zip الخاص بعيّنة hls_js/simple إلى مجلد جديد. هذا المثال هو تطبيق ويب يمكنك استضافته محليًا لأغراض الاختبار.
لاستضافة المثال محليًا، انتقِل إلى المجلد الجديد، ونفِّذ أمر Python التالي لبدء خادم ويب:
python3 -m http.server 8000لا تتوفّر http.server إلا في Python 3.x. يمكنك استخدام أي خادم ويب آخر، مثل خادم Apache HTTP أو Node JS.
افتح متصفّح ويب وانتقِل إلى localhost:8000 للاطّلاع على مشغّل فيديو.
يجب أن يتوافق المتصفّح مع مكتبة HLS.js.
إذا كان كل شيء يعمل بشكل صحيح، سيؤدي النقر على زر تشغيل في مشغّل الفيديو إلى بدء الفيلم القصير "Tears of Steel"، مع فواصل إعلانية كل 30 ثانية.
طلب بث فيديو عند الطلب
لاستبدال عيّنة البث ببث الفيديو عند الطلب (VOD) الذي تمّت إضافة الإعلانات إليه، استخدِم الفئة
VideoStitcherVodStreamRequest
لإنشاء جلسة إعلانية تلقائيًا باستخدام "مدير إعلانات Google". يمكنك استخدام واجهة مستخدم "إدارة إعلانات Google" من أجل تحديد موقع جلسات "الإعلانات الديناميكية أثناء البث" التي تم إنشاؤها لأغراض المراقبة وتصحيح الأخطاء.
في النموذج الحالي، تتوفّر دوال لطلب بث فيديو عند الطلب أو بث مباشر. لكي تعمل مع Google Cloud Video Stitcher API، عليك إضافة دالة جديدة لعرض عنصر VideoStitcherVodStreamRequest.
وفي ما يلي مثال لذلك:
// StreamManager which will be used to request DAI 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() {
requestVodVideoStitcherStream();
playButton.style.display = "none";
playButton.removeEventListener('click', initiatePlayback);
playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
streamRequest.vodConfigId = 'VOD_CONFIG_ID';
streamRequest.region = 'LOCATION';
streamRequest.projectNumber = 'PROJECT_NUMBER';
streamRequest.oAuthToken = 'OAUTH_TOKEN';
streamRequest.networkCode = 'NETWORK_CODE';
streamManager.requestStream(streamRequest);
}
إعادة تحميل الصفحة بعد ذلك، يمكنك طلب بث الفيديو حسب الطلب المخصّص وتشغيله.
(اختياري) إضافة خيارات جلسة البث
خصِّص طلب البث المباشر من خلال إضافة خيارات الجلسة لتجاوز الإعدادات التلقائية لواجهة برمجة التطبيقات Cloud Video Stitcher API باستخدام VideoStitcherVodStreamRequest.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 API وطلبت بثه باستخدام حزمة تطوير البرامج للإعلانات الديناميكية أثناء عرض الفيديو (DAI) من "الإعلانات التفاعلية" (IMA) بتنسيق HTML5، من المهم إيقاف أي موارد عرض.
اتّبِع دليل تنظيف الفيديو عند الطلب لإزالة أي موارد ومواد عرض غير ضرورية.
أخيرًا، في نافذة الوحدة الطرفية التي بدأت فيها خادم الويب Python 3، استخدِم الأمر ctrl+C لإنهاء الخادم المحلي.