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

اختيار النظام الأساسي: HTML5 Android

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

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

يتطلّب التحميل المسبق الإصدار 3.17.0 أو إصدارًا أحدث من حزمة IMA Android SDK.

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

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

@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 الخاص بالإعلان مسبقًا، بغض النظر عن إعداد التحميل المسبق هذا.