تتيح حزمة تطوير البرامج لإعلانات الوسائط التفاعلية إمكانية التحميل المُسبَق لمواد عرض إعلانات الفيديو. يمكنك تفعيل هذه الميزة في عملية دمج حزمة SDK لتوفير انتقال أكثر سلاسة بين الإعلانات والمحتوى. يتناول هذا الدليل التفاصيل الفنية المتعلقة بتنفيذ ميزة التحميل المُسبَق للوسائط باستخدام "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية".
المتطلبات الأساسية
يتطلّب التحميل المُسبَق الإصدار 3.17.0 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android من IMA.
تفعيل التحميل المُسبَق
لتفعيل التحميل المُسبق، استخدِمAdsRenderingSettings.setEnablePreloading()
لضبط التحميل المُسبق على "صحيح". يجب تنفيذ هذا الإجراء خلال onAdsManagerLoaded()
callback:
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
...
AdsRenderingSettings adsRenderingSettings =
ImaSdkFactory.getInstance().createAdsRenderingSettings();
adsRenderingSettings.setEnablePreloading(true);
mAdsManager.init(adsRenderingSettings);
}
إتاحة التحميل المُسبَق باستخدام VideoAdPlayer مخصّص
ننصحك باستخدام إضافة ExoPlayer-IMA المستخدَمة في تطبيق ExoPlayer التجريبي على Android. عند دمج إضافة ExoPlayer-IMA، يتم تفعيل التحميل المُسبَق تلقائيًا وتتضمّن الإضافة ميزة التحميل المُسبَق المضمّنة.
في حال تنفيذ ميزة التحميل المُسبَق بدون إضافة ExoPlayer-IMA،
يجب إجراء تغييرات إضافية بعد استدعاء setEnablePreloading(). لكي يتمكّن مشغّل الفيديو من عرض الإعلانات مسبقًا، يجب أن يتتبّع عناصر AdMediaInfo التي يتم تمريرها في الطلبات من loadAd() وplayAd()، وأن يتضمّن AdMediaInfo الصحيح في طلبات AdPlayerCallback. وقد يتطلّب ذلك بنية بيانات لإدارة عناصر AdMediaInfo، علمًا بأنّه قد يحدث loadAd() لـ AdMediaInfo لاحق أثناء تشغيل AdMediaInfo سابق. يوضّح المثال التالي بعض التغييرات التي قد تحتاج إلى إجرائها لكي يتيح تطبيقك ميزة التحميل المُسبَق:
// enum for cases of PlayerState.
static enum PlayerState {
IDLE,
LOADED,
PLAYING,
PAUSED,
}
...
private final List<VideoAdPlayer.VideoAdPlayerCallback> callbacks;
private final ArrayList<AdMediaInfo> mediaInfos = new ArrayList<>();
private PlayerState playerState;
private boolean adCurrentlyLoaded;
...
@Override
public void playAd(AdMediaInfo adMediaInfo) {
switch (playerState) {
case LOADED:
for (VideoAdPlayerCallback callback : callbacks) {
callback.onPlay(adMediaInfo);
}
break;
case PAUSED:
for (VideoAdPlayerCallback callback : callbacks) {
callback.onResume(adMediaInfo);
}
break;
case PLAYING:
// Intentionally and silently ignore since it is already playing from a prior media item,
// note that onPlay is triggered by positionDiscontinuity.
return;
case IDLE:
throw new IllegalStateException("Call to playAd when player state is not LOADED.");
}
playerState = PlayerState.PLAYING;
player.setPlayWhenReady(true);
}
@Override
public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) {
if (adCurrentlyLoaded == true) {
mediaInfos.add(adMediaInfo);
return;
}
player.stop();
player.seekTo(0);
mediaInfos.clear();
mediaInfos.add(adMediaInfo);
player.setPlayWhenReady(false);
player.loadMedia(adMediaInfo.getUrl());
playerState = PlayerState.LOADED;
adCurrentlyLoaded = true;
}
@Override
public void stopAd(AdMediaInfo adMediaInfo) {
if (allAdsInBreakHavePlayed()) {
if (isFinalAd(adMediaInfo)) {
// handle clean up after all ads have played.
} else {
seekToNextItem(player);
}
} else {
mediaInfos.remove(adMediaInfo);
}
}
private boolean allAdsInBreakHavePlayed() {
// Code to determine if all the ads in the current ad break have completed.
}
private boolean isFinalAd(AdMediaInfo adMediaInfo) {
// Code to determine if this adMediaInfo is the final ad.
}
private void seekToNextItem(YourPlayerClass player) {
// Code to seek your player to the next media item.
}
اختبار عمليات التنفيذ المخصّصة للتحميل المُسبَق
بالنسبة إلى عمليات التنفيذ المخصّصة للتحميل المُسبَق، يُنصح باختبار الحالات الحدّية التالية للتحقّق من صحة إعداد التحميل المُسبَق:
- إعلان واحد يسبق عرض المحتوى
- إعلان يسبق عرض المحتوى ضمن مجموعة إعلانات متسلسلة من 3 إعلانات
- إعلان أثناء التشغيل ضمن مجموعة إعلانات متسلسلة من 3 إعلانات
- محاولة الانتقال إلى إعلان وسطي ثانٍ بعد أن يبدأ التحميل المُسبَق للإعلان الوسطي الأول ولكن قبل تشغيله
- تشغيل الإعلان بعد انتهاء الفيديو
التوقيت
يلخّص الجدول التالي التغييرات في توقيت عرض الإعلانات عند تفعيل ميزة التحميل المسبق:
| الحدث | مع التحميل المُسبَق | بدون التحميل المُسبَق |
|---|---|---|
| طلب إعلان VAST | AdsLoader.requestAds() |
AdsLoader.requestAds() |
| تم تحميل إعلان ما قبل التشغيل (إعلان واحد) | AdsManager.init() |
AdsManager.start() |
| تم تحميل إعلان ما قبل التشغيل (VMAP/قواعد الإعلانات) | AdsManager.init() |
AdsManager.init() |
| تم تحميل إعلان أثناء التشغيل أو ما بعد التشغيل | بالنسبة إلى الإعلان الأول في فاصل إعلاني، قبل 8 ثوانٍ من وقت بدء الإعلان بالنسبة إلى الإعلانات المتتالية، عندما يبدأ تشغيل الإعلان السابق | في وقت بدء الإعلان |
الأسئلة الشائعة
- هل يؤدي التحميل المُسبَق للوسائط إلى تحميل تصميم الإعلان الكامل؟
- لا، لا يتم عادةً تحميل تصميم الإعلان بالكامل عند بدء تشغيل الإعلان. يهدف التحميل المُسبَق إلى تحسين تجربة المستخدم من خلال تقليل الوقت الذي يستغرقه تحميل الإعلان. وهي غير مخصّصة لعرض الإعلانات بلا اتصال بالإنترنت.
- هل يجب تفعيل ميزة التحميل المُسبَق للوسائط من أجل نموذج عرض إعلانات الفيديو (VAST) الخاص بالإعلان بالإضافة إلى الوسائط؟
- لا، تحمّل حزمة تطوير البرامج (SDK) دائمًا ملف VAST الخاص بالإعلان مسبقًا، بغض النظر عن إعداد التحميل المسبق هذا.