تتيح حزمة IMA SDK التحميل المُسبَق لمواد عرض إعلانات الفيديو. يمكنك تفعيل هذه الميزة في عملية دمج حزمة SDK لتوفير انتقال أكثر سلاسة بين الإعلانات والمحتوى. يتناول هذا الدليل التفاصيل الفنية المتعلقة بتنفيذ ميزة التحميل المُسبَق للوسائط باستخدام "حزمة تطوير البرامج للإعلانات التفاعلية (IMA 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 المستخدَمة في تطبيق Android ExoPlayer التجريبي. عند دمج إضافة 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 الخاص بالإعلان، بغض النظر عن إعداد التحميل المسبق هذا.