التحميل المسبق للوسائط

تتيح حزمة تطوير البرامج لإعلانات الوسائط التفاعلية التحميل المُسبق لمواد عرض إعلانات الفيديو. يمكنك تفعيل هذه الميزة في عملية دمج حزمة تطوير البرامج (SDK) لتوفير انتقال أكثر سلاسة بين الإعلانات والمحتوى. يشرح هذا الدليل التفاصيل الفنية لتنفيذ التحميل المُسبق للوسائط باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.

المتطلبات الأساسية

يتطلب التحميل المُسبق الإصدار 3.17.0 أو إصدارًا أحدث من حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لنظام التشغيل Android.

تفعيل التحميل المُسبق

لتفعيل التحميل المُسبق، استخدِم AdsRenderingSettings.setEnablePreloading() لضبط التحميل المُسبق على "صحيح". يجب أن يتم ذلك خلال معاودة الاتصال بـ onAdsManagerLoaded():

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
  ...
  AdsRenderingSettings adsRenderingSettings =
      ImaSdkFactory.getInstance().createAdsRenderingSettings();
  adsRenderingSettings.setEnablePreloading(true);
  mAdsManager.init(adsRenderingSettings);
}

دعم التحميل المُسبق باستخدام VideoAdPlayer المخصّص

نقترح استخدام إضافة ExoPlayer-IMA المستخدمة في تطبيق Android BasicExample. عند دمج إضافة 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) للإعلان مسبقًا، بغض النظر عن إعداد التحميل المسبق هذا.