تتيح حزمة IMA SDK التحميل المُسبَق لمواد عرض إعلانات الفيديو. يمكنك تفعيل هذه الميزة في عملية دمج حزمة 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() |
| تم تحميل إعلان ما قبل التشغيل (قائمة تشغيل إعلانات الفيديو المتعددة/قواعد الإعلانات) | AdsManager.init() |
AdsManager.init() |
| تم تحميل إعلان أثناء التشغيل أو إعلان ما بعد التشغيل | بالنسبة إلى الإعلان الأول في فاصل إعلاني، قبل 8 ثوانٍ من وقت بدء الإعلان بالنسبة إلى الإعلانات المتتالية، عندما يبدأ تشغيل الإعلان السابق | في وقت بدء الإعلان |
الأسئلة الشائعة
- هل يؤدي التحميل المُسبَق للوسائط إلى تحميل تصميم الإعلان الكامل؟
- لا، لا يتم عادةً تحميل تصميم الإعلان بالكامل عند بدء تشغيل الإعلان. يهدف التحميل المُسبَق إلى تحسين تجربة المستخدم من خلال تقليل الوقت الذي يستغرقه تحميل الإعلان. وهي غير مخصّصة لعرض الإعلانات بلا إنترنت.
- هل يجب تفعيل التحميل المُسبَق للوسائط من أجل نموذج عرض إعلانات الفيديو (VAST) الخاص بالإعلان بالإضافة إلى الوسائط؟
- لا، تحمّل حزمة تطوير البرامج (SDK) دائمًا ملف VAST الخاص بالإعلان مسبقًا، بغض النظر عن إعداد التحميل المسبق هذا.