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

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

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

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

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

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

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

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

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

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

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

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

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

preloadManager.invalidate()
PreloadManagerKotlinSnippets.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()
PreloadManagerKotlinSnippets.kt

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

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

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

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

preloadManager.remove(mediaItem)
PreloadManagerKotlinSnippets.kt

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

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

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

preloadManager.release()
PreloadManagerKotlinSnippets.kt

preloadManager.release()

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

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