إدارة المحتوى وتشغيله

توضّح هذه الصفحة كيفية استخدام مدير التحميل المسبق لإدارة محتوى الفيديو. باستخدام مدير التحميل المسبق، يمكنك منح المستخدم تجربة أفضل. فعندما ينتقل المستخدم من عنصر وسائط إلى آخر، يبدأ التشغيل بشكل أسرع لأنّ المدير سبق أن حمّل بعض المحتوى.

تتناول هذه الصفحة المواضيع التالية:

إضافة عناصر وسائط إلى مدير التحميل المسبق

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

إنّ إضافة عناصر الوسائط لا تؤدي بحد ذاتها إلى بدء مدير التحميل المسبق في تحميل المحتوى. لبدء التحميل المسبق، عليك إبطال الأولويات في مدير التحميل المسبق.

val initialMediaItems = pullMediaItemsFromService(count = 20)
for (index in 0 until initialMediaItems.size) {
  preloadManager.add(initialMediaItems[index], /* rankingData= */ index)
}
// items aren't actually loaded yet! need to call invalidate() after this
PreloadManagerManagePlay.kt

نقاط أساسية حول الرمز

  • توضّح هذه المقتطفة كيفية ملء مدير التحميل المسبق في البداية بعد إنشائه. يمكنك أيضًا استدعاء add() لإضافة عناصر إلى مدير تحميل مسبق حالي تم ملؤه.
  • في هذه المقتطفة، pullMediaItemsFromService() هي منطق التطبيق لجلب قائمة المحتوى الذي سيتم تشغيله. يستدعي الرمز هذه الطريقة لجلب قائمة تضم ما يصل إلى 20 عنصرًا.
  • preloadManager هو DefaultPreloadManager الذي تم إنشاؤه في إنشاء DefaultPreloadManager. يستدعي الرمز طريقة add() لهذا المدير لإضافة كل عنصر في منصّة العرض الدوّارة.
  • rankingData هي قيمة يستخدمها مدير التحميل المسبق لتحديد أولوية كل عنصر وسائط. بالنسبة إلى DefaultPreloadManager، يكون rankingData عددًا صحيحًا يمثّل موضع العنصر في منصّة العرض الدوّارة. يحدّد مدير التحميل المسبق الأولوية حسب مدى بُعد كل عنصر عن العنصر الذي يتم تشغيله حاليًا.

إبطال الأولويات في مدير التحميل المسبق

لبدء مدير التحميل المسبق في تحميل المحتوى مسبقًا، عليك استدعاء invalidate() لإعلام مدير التحميل المسبق بأنّ أولويات العناصر غير محدّثة. عليك إجراء ذلك في الحالات التالية:

  • عند إضافة عناصر وسائط جديدة إلى مدير التحميل المسبق أو إزالة عناصر وسائط. إذا كنت تضيف عدة عناصر أو تزيلها، عليك إضافة جميعها ثم استدعاء invalidate().
  • عندما ينتقل المستخدم من عنصر وسائط إلى آخر. في هذه الحالة، عليك التأكّد من تعديل فهرس التشغيل الحالي قبل استدعاء invalidate()، كما هو موضّح في جلب المحتوى وتشغيله.

عند إبطال مدير التحميل المسبق، يستدعي TargetPreloadStatusControl الذي أنشأته لمعرفة مقدار المحتوى الذي يجب تحميله من كل عنصر. بعد ذلك، يتم تحميل محتوى كل عنصر بترتيب الأولوية من الأعلى إلى الأدنى.

preloadManager.invalidate()
PreloadManagerManagePlay.kt

نقاط أساسية حول الرمز

  • يؤدي استدعاء invalidate() إلى إعادة تقييم مدير التحميل المسبق لأولوية كل عنصر وسائط يعرفه. لهذا السبب، إذا كنت تُجري الكثير من التغييرات على مدير التحميل المسبق، عليك الانتهاء من إجراء التغييرات قبل استدعاء invalidate().

جلب الوسائط وتشغيلها

عندما ينتقل المستخدم إلى عنصر وسائط جديد، عليك الحصول على عنصر الوسائط من مدير التحميل المسبق. إذا حمّل مدير التحميل المسبق أيًا من المحتوى، يتم تشغيل المحتوى بشكل أسرع مما لو لم تستخدم مدير التحميل المسبق. إذا لم يحمّل مدير التحميل المسبق محتوى من هذا العنصر بعد، يتم تشغيل المحتوى بشكل طبيعي.

// When a media item is about to display on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
  player.setMediaSource(mediaSource)
} else {
  // If mediaSource is null, that mediaItem hasn't been added to the preload manager
  // yet. So, send it directly to the player when it's about to play
  player.setMediaItem(mediaItem)
}
player.prepare()

// When the media item is displaying at the center of the screen
player.play()
preloadManager.setCurrentPlayingIndex(currentIndex)

// Need to call invalidate() to update the priorities
preloadManager.invalidate()
PreloadManagerManagePlay.kt

نقاط أساسية حول الرمز

  • player هو ExoPlayer في Media3 الذي يستخدمه التطبيق لتشغيل المحتوى. عليك إنشاء هذا المشغّل من خلال استدعاء DefaultPreloadManager.Builder.buildExoPlayer() على أداة الإنشاء نفسها التي استخدمتها لإنشاء مدير التحميل المسبق.
  • عندما ينتقل المستخدم إلى عنصر وسائط جديد، يستدعي التطبيق getMediaSource() للحصول على مصدر الوسائط من مدير التحميل المسبق. يجب أن يكون هذا mediaItem قد أضفته إلى مدير التحميل المسبق. لا بأس إذا لم يكن مدير التحميل المسبق قد بدأ تحميل المحتوى بعد. في هذه الحالة، يعرض MediaSource لا يتضمّن بيانات تم تحميلها مسبقًا. على سبيل المثال، قد يحدث ذلك إذا انتقل المستخدم فجأة إلى موضع بعيد في منصّة العرض الدوّارة.
  • بعد أن يشغّل المستخدم عنصر الوسائط الجديد، استدعِ setCurrentPlayingIndex لإعلام مدير التحميل المسبق بموضع العنصر الجديد في منصّة العرض الدوّارة. يحتاج مدير التحميل المسبق إلى هذه المعلومات لتحديد أولوية تحميل العنصر التالي. بعد تعديل الفهرس الحالي، استدعِ invalidate() لجعل مدير التحميل المسبق يعيد تحديد أولوية كل عنصر.

إزالة العناصر من مدير التحميل المسبق

للحفاظ على كفاءة مدير التحميل المسبق، عليك إزالة العناصر التي لم يعُد مدير التحميل المسبق بحاجة إلى تتبّعها. يمكنك أيضًا إزالة العناصر التي لا تزال في منصّة العرض الدوّارة، ولكنها بعيدة عن موضع المستخدم الحالي. على سبيل المثال، يمكنك أن تقرّر أنّه إذا كان العنصر على بُعد أكثر من 15 عنصرًا من المحتوى الذي يشاهده المستخدم، فلا داعي لتحميله مسبقًا. في هذه الحالة، عليك إزالة العناصر عندما تصبح بعيدة بهذا القدر. إذا عاد المستخدم إلى هذه العناصر التي تمت إزالتها، يمكنك دائمًا إضافتها مرة أخرى.

preloadManager.remove(mediaItem)
PreloadManagerManagePlay.kt

نقاط أساسية حول الرمز

إيقاف مدير التحميل المسبق عند الانتهاء من استخدامه

عندما لم تعُد بحاجة إلى مدير التحميل المسبق، عليك إيقافه لتحرير موارده. على وجه الخصوص، احرص على إيقافه عند إيقاف نشاطك.

preloadManager.release()
PreloadManagerManagePlay.kt

نقاط أساسية حول الرمز

  • يجب عدم استدعاء أي من طرق الكائن بعد إيقافه.
  • إذا كنت بحاجة إلى إنشاء مدير تحميل مسبق آخر، أنشئ DefaultPreloadManager.Builder جديدًا واستخدِمه لإنشاء DefaultPreloadManager. لا تحاول إعادة استخدام أداة الإنشاء القديمة.