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

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

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

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

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

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

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

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

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

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

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

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

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

preloadManager.invalidate()

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

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

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

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

// When a media item is about to display on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
    player.setMediaSource(mediaSource)
}
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()

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

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

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

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

preloadManager.remove(mediaItem)

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

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

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

preloadManager.release()

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

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