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

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

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

يتطلب التحميل المُسبَق توفُّر الإصدار 3.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android من IMA.

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

لتفعيل التحميل المُسبَق، استخدِم AdsRenderingSettings.setEnablePreloading() لضبط التحميل المُسبَق على true. يجب تنفيذ ذلك في 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 للإعلان بغض النظر عن إعداد التمهيد المُسبَق هذا.