تُسهِّل أدوات تطوير البرامج لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. ويمكن أن تطلب أدوات تطوير البرامج لإعلانات الوسائط التفاعلية إعلانات من أي خادم متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام أدوات تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) من جهة العميل، يمكنك التحكّم في تشغيل الفيديو، بينما تعالج حزمة تطوير البرامج (SDK) تشغيل الإعلان. يتم تشغيل الإعلانات في مشغّل فيديو منفصل يتم عرضه أعلى مشغّل الفيديو للمحتوى في التطبيق.
يوضح هذا الدليل كيفية دمج أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) في تطبيق بسيط لمشغل الفيديو. إذا كنت ترغب في عرض دمج نموذجي مكتمل أو متابعة العملية، فعليك بتنزيل المثال البسيط من GitHub. إذا كنت مهتمًا بمشغّل HTML5 مع حزمة SDK مدمجة مسبقًا، اطّلِع على المكوّن الإضافي IMA SDK لـ Video.js.
نظرة عامة على جانب إعلانات الوسائط التفاعلية
يتضمن تنفيذ برنامج IMA من جانب العميل أربعة مكونات SDK رئيسية موضحة في هذا الدليل:
AdDisplayContainer: كائن حاوية حيث يتم عرض الإعلانات.AdsLoader: كائن يطلب إعلانات ويعالج الأحداث من الردود على طلبات الإعلانات. يجب عليك تحديد أداة واحدة لتحميل الإعلانات يمكن إعادة استخدامها طوال فترة استخدام التطبيق.AdsRequest: كائن يعرّف طلب الإعلانات. وتحدّد طلبات الإعلانات عنوان URL لعلامة إعلان VAST، بالإضافة إلى معلمات إضافية مثل أبعاد الإعلان.AdsManager: كائن يحتوي على استجابة لطلب الإعلانات، ويتحكم في تشغيل الإعلان، ويستمع إلى أحداث الإعلانات التي يتم إطلاقها بواسطة SDK.
المتطلبات الأساسية
قبل البدء، ستحتاج إلى ما يلي:
- ثلاثة ملفات فارغة:
- index.html
- style.css
- ads.js
- تثبيت Python على جهاز الكمبيوتر أو على خادم ويب لاستخدامه في الاختبار
1- بدء خادم التطوير
ونظرًا لأن أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) تحمِّل التبعيات عبر البروتوكول ذاته الذي يتم تحميلها منه، عليك استخدام خادم ويب لاختبار تطبيقك. وأبسط طريقة لبدء خادم تطوير محلي هي استخدام الخادم المدمج في Python.
- باستخدام سطر الأوامر، من الدليل الذي يحتوي على
ملف index.html الذي يتم تشغيله:
python -m http.server 8000
- في متصفح الويب، انتقل إلى
http://localhost:8000/
يمكنك أيضًا استخدام أي خادم ويب آخر، مثل خادم Apache HTTP.
2. إنشاء مشغل فيديو بسيط
أولاً، عدّل index.html لإنشاء عنصر فيديو HTML5 بسيط مضمّن في عنصر التفاف وزر لبدء التشغيل. أضِف العلامات الضرورية أيضًا لتحميل ملفي style.css وads.js. عدِّل بعد ذلك styles.css لجعل مشغّل الفيديو يستجيب للأجهزة الجوّالة. أخيرًا، في ads.js، شغِّل تشغيل الفيديو عند النقر على زر التشغيل.
index.html
<!doctype html>
<html lang="en">
<head>
<title>IMA HTML5 Simple Demo</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="style.css">
</head>
<body>
<div id="page-content">
<div id="video-container">
<video id="video-element">
<source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
<source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
</video>
</div>
<button id="play-button">Play</button>
</div>
<script src="ads.js"></script>
</body>
</html>
style.css
#page-content {
position: relative;
/* this element's width controls the effective height */
/* of the video container's padding-bottom */
max-width: 640px;
margin: 10px auto;
}
#video-container {
position: relative;
/* forces the container to match a 16x9 aspect ratio */
/* replace with 75% for a 4:3 aspect ratio, if needed */
padding-bottom: 56.25%;
}
#video-element {
/* forces the contents to fill the container */
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
ads.js
var videoElement;
// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
videoElement = document.getElementById('video-element');
var playButton = document.getElementById('play-button');
playButton.addEventListener('click', function(event) {
videoElement.play();
});
});
بعد إكمال هذه الخطوة، عندما تفتح index.html في المتصفح (عبر خادم التطوير)، من المفترض أن تتمكن من رؤية عنصر الفيديو ومن المفترض أن يبدأ تشغيل الفيديو عند النقر على زر التشغيل.
3- استيراد أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA)
بعد ذلك، أضِف إطار عمل إعلانات الوسائط التفاعلية باستخدام علامة نص برمجي في index.html، قبل علامة ads.js.
...
</video>
</div>
<button id="play-button">Play</button>
</div>
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
<script src="ads.js"></script>
</body>
</html>
4. إرفاق معالجات الصفحة ومُشغِّل الفيديو
لتعديل سلوك مشغّل الفيديو باستخدام JavaScript، أضِف معالجات الأحداث التي تؤدي إلى تنفيذ الإجراءات التالية:
- عند الانتهاء من تحميل الصفحة، عليك تهيئة أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA).
- عند النقر على زر تشغيل الفيديو، يمكنك تحميل الإعلانات (ما لم يتم تحميل إعلانات).
- عند تغيير حجم نافذة المتصفّح، يجب تعديل عنصر الفيديو وسمات
adsManagerلجعل الصفحة متجاوبة على الأجهزة الجوّالة.
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;
window.addEventListener('load', function(event) {
videoElement = document.getElementById('video-element');
initializeIMA();
videoElement.addEventListener('play', function(event) {
loadAds(event);
});
var playButton = document.getElementById('play-button');
playButton.addEventListener('click', function(event) {
videoElement.play();
});
});
window.addEventListener('resize', function(event) {
console.log("window resized");
});
function initializeIMA() {
console.log("initializing IMA");
}
function loadAds(event) {
// Prevent this function from running on if there are already ads loaded
if(adsLoaded) {
return;
}
adsLoaded = true;
// Prevent triggering immediate playback when ads are loading
event.preventDefault();
console.log("loading ads");
}
5- إنشاء حاوية الإعلان
في معظم المتصفحات، تستخدم أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) عنصر حاوية إعلان مخصّصًا لعرض كل من الإعلانات وعناصر واجهة المستخدم ذات الصلة بالإعلانات. يجب تغيير حجم هذه الحاوية لتراكب عنصر الفيديو من
الركن العلوي الأيمن. يتم ضبط ارتفاع وعرض الإعلانات الموضوعة في هذه الحاوية بواسطة
الكائن adsManager، لذلك لا تحتاج إلى ضبط هذه القيم يدويًا.
لتنفيذ عنصر حاوية الإعلان هذا، عليك أولاً إنشاء div جديد داخل العنصر video-container. بعد ذلك، عدِّل CSS لوضع العنصر في أعلى يمين video-element. وأخيرًا، حدِّد متغيّرًا للحاوية ضمن الدالة initializeIMA() التي تعمل عند تحميل الصفحة.
...
<div id="video-container">
<video id="video-element" controls>
<source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
<source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
</video>
<div id="ad-container"></div>
</div>
...
style.css
...
#ad-container {
position: absolute;
top: 0;
left: 0;
width: 100%;
}
ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
...
function initializeIMA() {
console.log("initializing IMA");
adContainer = document.getElementById('ad-container');
}
6. تهيئة AdsLoader وتقديم طلب إعلانات
لطلب مجموعة من الإعلانات، أنشئ مثيل ima.AdsLoader. يأخذ هذا المثيل كائن AdDisplayContainer كإدخال ويمكن استخدامه لمعالجة كائنات ima.AdsRequest المرتبطة بعنوان URL لعلامة إعلان محددة. تحتوي علامة الإعلان المستخدمة في
هذا المثال على إعلان ما قبل التشغيل لمدة 10 ثوانٍ. يمكنك اختبار عنوان URL لعلامة الإعلان هذا أو أي عنوان URL آخر باستخدام
أداة فحص مجموعة إعلانات الفيديو لإعلانات الوسائط التفاعلية.
كإحدى أفضل الممارسات، يجب الاحتفاظ بنسخة واحدة فقط من ima.AdsLoader خلال
دورة حياة الصفحة بأكملها. لإنشاء طلبات إعلان إضافية، أنشئ كائن ima.AdsRequest
جديدًا، ولكن أعِد استخدام ima.AdsLoader نفسه. لمزيد من المعلومات، راجع الأسئلة الشائعة حول أداة تطوير البرامج لإعلانات الوسائط التفاعلية.
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
...
function initializeIMA() {
console.log("initializing IMA");
adContainer = document.getElementById('ad-container');
adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
adsLoader = new google.ima.AdsLoader(adDisplayContainer);
// Let the AdsLoader know when the video has ended
videoElement.addEventListener('ended', function() {
adsLoader.contentComplete();
});
var adsRequest = new google.ima.AdsRequest();
adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';
// Specify the linear and nonlinear slot sizes. This helps the SDK to
// select the correct creative if multiple are returned.
adsRequest.linearAdSlotWidth = videoElement.clientWidth;
adsRequest.linearAdSlotHeight = videoElement.clientHeight;
adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;
// Pass the request to the adsLoader to request ads
adsLoader.requestAds(adsRequest);
}
7- الاستماع إلى أحداث AdsLoader
عند تحميل الإعلانات بنجاح، يُنشئ ima.AdsLoader
حدث ADS_MANAGER_LOADED. يمكنك تحليل الحدث الذي تم تمريره إلى معاودة الاتصال لإعداد الكائن AdsManager. يحمّل AdsManager الإعلانات الفردية على النحو المحدّد في الرد على عنوان URL لعلامة الإعلان.
بالإضافة إلى ذلك، تأكد من التعامل مع أي أخطاء قد تحدث أثناء عملية التحميل. إذا لم يتم تحميل الإعلانات، تأكّد من استمرار تشغيل الوسائط بدون إعلانات، بحيث لا تتعارض مع تجربة المستخدم.
ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;
...
function initializeIMA() {
console.log("initializing IMA");
adContainer = document.getElementById('ad-container');
adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
adsLoader = new google.ima.AdsLoader(adDisplayContainer);
adsLoader.addEventListener(
google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
onAdsManagerLoaded,
false);
adsLoader.addEventListener(
google.ima.AdErrorEvent.Type.AD_ERROR,
onAdError,
false);
...
function onAdsManagerLoaded(adsManagerLoadedEvent) {
// Instantiate the AdsManager from the adsLoader response and pass it the video element
adsManager = adsManagerLoadedEvent.getAdsManager(
videoElement);
}
function onAdError(adErrorEvent) {
// Handle the error logging.
console.log(adErrorEvent.getError());
if(adsManager) {
adsManager.destroy();
}
}
8. بدء مدير الإعلانات
لبدء تشغيل الإعلان، يجب تشغيل AdsManager. لدعم متصفّحات الأجهزة الجوّالة
بشكل كامل، يجب أن يتم ذلك من خلال تفاعل المستخدم.
...
function loadAds(event) {
// prevent this function from running on every play event
if(adsLoaded) {
return;
}
adsLoaded = true;
// prevent triggering immediate playback when ads are loading
event.preventDefault();
console.log("loading ads");
// Initialize the container. Must be done via a user action on mobile devices.
videoElement.load();
adDisplayContainer.initialize();
var width = videoElement.clientWidth;
var height = videoElement.clientHeight;
try {
adsManager.init(width, height, google.ima.ViewMode.NORMAL);
adsManager.start();
} catch (adError) {
// Play the video without ads, if an error occurs
console.log("AdsManager could not be started");
videoElement.play();
}
}
...
9. جعل AdsManager متجاوبًا
للتأكّد من تغيير حجم الإعلانات ديناميكيًا لتتطابق مع حجم مشغّل الفيديو، يجب أن يستدعي حدث تغيير حجم النافذة adsManager.resize() في حال تغيّر حجم الشاشة أو اتجاهها.
...
window.addEventListener('resize', function(event) {
console.log("window resized");
if(adsManager) {
var width = videoElement.clientWidth;
var height = videoElement.clientHeight;
adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
}
});
...
10. الاستماع إلى أحداث AdsManager
يُطلِق AdsManager أيضًا العديد من الأحداث التي يجب معالجتها. وتُستخدَم هذه الأحداث
لتتبُّع التغيّرات في الحالة، وتشغيل الفيديو وإيقافه مؤقتًا، وتسجيل الأخطاء.
معالجة الأخطاء
يمكن أن يعمل معالج الأخطاء الذي تم إنشاؤه لـ AdsLoader كمعالج لأخطاء
AdsManager من خلال إضافة معالج أحداث جديد مع وظيفة رد الاتصال نفسها.
...
function onAdsManagerLoaded(adsManagerLoadedEvent) {
adsManager = adsManagerLoadedEvent.getAdsManager(
videoElement);
adsManager.addEventListener(
google.ima.AdErrorEvent.Type.AD_ERROR,
onAdError);
}
...
تشغيل الأحداث وإيقافها مؤقتًا
عندما تكون السمة AdsManager جاهزة لإدراج إعلان لعرضه، سيتم تنشيط
الفعالية CONTENT_PAUSE_REQUESTED. يمكنك معالجة هذا الحدث من خلال تشغيل إيقاف مؤقت
في مشغّل الفيديو الأساسي. وبالمثل، عند اكتمال عرض أحد الإعلانات، يعمل AdsManager على تنشيط
فعالية CONTENT_RESUME_REQUESTED. يمكنك معالجة هذا الحدث من خلال إعادة تشغيل الفيديو
المضمّن في الفيديو.
...
function onAdsManagerLoaded(adsManagerLoadedEvent) {
adsManager = adsManagerLoadedEvent.getAdsManager(
videoElement);
adsManager.addEventListener(
google.ima.AdErrorEvent.Type.AD_ERROR,
onAdError);
adsManager.addEventListener(
google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
onContentPauseRequested);
adsManager.addEventListener(
google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
onContentResumeRequested);
}
...
function onContentPauseRequested() {
videoElement.pause();
}
function onContentResumeRequested() {
videoElement.play();
}
تشغيل النقر للإيقاف المؤقت على أجهزة الجوّال
بما أنّ AdContainer تتراكب على عنصر الفيديو، لا يمكن للمستخدمين التفاعل مباشرةً
مع المشغِّل الأساسي. يمكن أن يؤدي ذلك إلى إرباك المستخدمين على أجهزة الجوّال الذين يتوقعون أن يتمكنوا من النقر على مشغّل الفيديو لإيقاف التشغيل مؤقتًا. لمعالجة هذه المشكلة، تمرِّر أداة تطوير البرامج لإعلانات الوسائط التفاعلية أي نقرات لا يتم التعامل معها بواسطة أداة تطوير البرامج لإعلانات الوسائط التفاعلية من تراكب الإعلان إلى العنصر AdContainer، حيث يمكن معالجتها. ولا ينطبق ذلك على الإعلانات الخطية على المتصفّحات غير المتوافقة مع الأجهزة الجوّالة، لأنّ النقر على الإعلان يؤدي إلى فتح
رابط النقر إلى الظهور.
لتنفيذ النقر لإيقاف الفيديو مؤقتًا، يمكنك إضافة معالج النقر إلى AdContainer وتشغيل أحداث التشغيل أو الإيقاف المؤقت على الفيديو الأساسي.
...
function initializeIMA() {
console.log("initializing IMA");
adContainer = document.getElementById('ad-container');
adContainer.addEventListener('click', adContainerClick);
adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
adsLoader = new google.ima.AdsLoader(adDisplayContainer);
...
function adContainerClick(event) {
console.log("ad container clicked");
if(videoElement.paused) {
videoElement.play();
} else {
videoElement.pause();
}
}
...
تشغيل المحتوى على الإعلانات غير الخطية
يوقف AdsManager الفيديو مؤقتًا عندما يكون الإعلان جاهزًا للعرض، ولكن
لا يراعي هذا السلوك الإعلانات غير الخطية، حيث من المفترض أن يستمر تشغيل المحتوى أثناء عرض الإعلان. لإتاحة عرض الإعلانات غير الخطية، استمع إلى AdsManager لبث
فعالية LOADED. بعد ذلك، تحقّق مما إذا كان الإعلان خطيًا أم لا، ثم استأنف تشغيله على
عنصر الفيديو.
...
function onAdsManagerLoaded(adsManagerLoadedEvent) {
adsManager = adsManagerLoadedEvent.getAdsManager(
videoElement);
adsManager.addEventListener(
google.ima.AdErrorEvent.Type.AD_ERROR,
onAdError);
adsManager.addEventListener(
google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
onContentPauseRequested);
adsManager.addEventListener(
google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
onContentResumeRequested);
adsManager.addEventListener(
google.ima.AdEvent.Type.LOADED,
onAdLoaded);
}
...
function onAdLoaded(adEvent) {
var ad = adEvent.getAd();
if (!ad.isLinear()) {
videoElement.play();
}
}
أكملت هذه الخطوة. أنت الآن تطلب إعلانات وتعرضها باستخدام أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA). للتعرّف على مزيد من ميزات SDK المتقدمة، يُرجى الاطّلاع على الأدلة الأخرى أو النماذج على GitHub.