تحديد المشاكل وحلّها

إصلاح الخطأ "حركة زيارات HTTP غير المسموح بها خالية من نصوص واضحة" الأخطاء

يحدث هذا الخطأ إذا كان تطبيقك يطلب حركة بيانات HTTP بالنص الواضح (أي http:// بدلاً من https://) عند تفعيل إعدادات أمان الشبكة لهذه الشبكة. وعدم السماح بذلك. إذا كان تطبيقك يستهدف Android 9 (المستوى 28 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، يجب استخدام cleartext. تم إيقاف زيارات HTTP من خلال الإعدادات التلقائية.

إذا كان تطبيقك يحتاج إلى العمل مع حركة زيارات HTTPS عبر بروتوكول HTTP، عليك استخدام تهيئة أمان الشبكة التي تسمح بذلك. الاطّلاع على مستندات أمان الشبكات لمزيد من التفاصيل. ولتفعيل جميع زيارات بروتوكول HTTP، يمكنك ببساطة إضافة android:usesCleartextTraffic="true" إلى العنصر application في تطبيقك AndroidManifest.xml

يستخدم تطبيق ExoPlayer التجريبي إعدادات أمان الشبكة التلقائية، ولذلك لا يسمح بحركة مرور HTTP لـ cleartext. يمكنك تفعيله باتّباع التعليمات أعلاه.

إصلاح "SSLHandshiException" و"CertPathValidatorException" و"ERR_CERT_AUTHORITY_غير" الأخطاء

SSLHandshakeException وCertPathValidatorException و تشير ERR_CERT_AUTHORITY_INVALID جميعها إلى مشكلة في طبقة المقابس الآمنة (SSL) للخادم الشهادة. لا تكون هذه الأخطاء خاصة بـ ExoPlayer. عرض مستندات طبقة المقابس الآمنة (SSL) في نظام التشغيل Android لمزيد من التفاصيل.

لماذا لا يمكن البحث عن بعض ملفات الوسائط؟

وفقًا للإعدادات التلقائية، لا تتيح ExoPlayer إتاحة التقديم/الترجيع في الوسائط حيث تكون الطريقة الوحيدة لإجراء عمليات بحث دقيقة، يجب أن يقوم اللاعب بفحص بالكامل. تعتبر ExoPlayer أنّ هذه الملفات غير قابلة للبحث. أحدث الوسائط تشتمل تنسيقات الحاويات على بيانات وصفية للتقديم (مثل نموذج فهرس)، والحصول على خوارزمية طلب محددة بشكل جيد (على سبيل المثال، بحث القسم الداخلي لـ Ogg)، أو إلى أن المحتوى بمعدل نقل بيانات ثابت. تُعد عمليات البحث الفعالة ممكن ومدعومة من قبل ExoPlayer في هذه الحالات.

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

لماذا يعتبر البحث عن محتوى غير دقيق في بعض ملفات MP3؟

إنّ ملفات MP3 ذات معدل نقل البيانات المتغير (VBR) غير مناسبة على الإطلاق لحالات الاستخدام التي التقديم/الترجيع بدقة. هناك سببان لذلك:

  1. للتقديم/الترجيع بدقة، سيوفر تنسيق الحاوية بشكل مثالي مقدارًا دقيقًا تعيين الوقت إلى البايت في العنوان. يتيح هذا التعيين للاعب تعيين طلب وقت البحث عن إزاحة البايت المقابلة، ثم ابدأ الطلب، تحليل وتشغيل الوسائط من تلك الإزاحة. العناوين المتاحة لـ فإن تحديد هذا التعيين في MP3 (مثل رؤوس XING) غالبًا ما غير دقيقة.
  2. بالنسبة إلى تنسيقات الحاويات التي لا توفّر تحديدًا دقيقًا للوقت بالبايت (أو أي تعيين من الوقت إلى البايت على الإطلاق)، فلا يزال من الممكن إجراء عملية ابحث عن ما إذا كانت الحاوية تتضمّن طوابع زمنية مطلقة لعيّنة في البث. ضِمن في هذه الحالة، يمكن للّاعب تحديد وقت التقديم بأفضل تخمين إزاحة البايت، ابدأ طلب الوسائط من تلك الإزاحة، حلِّل طابع زمني مطلق للعينة، وإجراء بحث ثنائي موجَّه بفعالية في وسائل الإعلام إلى أن تصل إلى العينة المناسبة لا يمكن تشغيل MP3 تضمين طوابع زمنية مطلقة لعينات في البث، وبالتالي لا ممكن.

لهذه الأسباب، الطريقة الوحيدة لإجراء بحث دقيق عن ملف VBR MP3 هو فحص الملف بالكامل وإنشاء تعيين وقت إلى بايت يدويًا في لاعب. يمكن تفعيل هذه الاستراتيجية باستخدام FLAG_ENABLE_INDEX_SEEKING، والتي يمكن ضبطها على DefaultExtractorsFactory باستخدام setMp3ExtractorFlags لاحظ أنه لا يمكن توسيعه إلى ملفات MP3 الكبيرة، لا سيّما إذا حاول المستخدم الوصول إلى نهاية البث قريبًا بعد بدء التشغيل، ما يتطلّب من المشغّل الانتظار حتى يتم تنزيله وفهرسوا البث بالكامل قبل تنفيذ البحث. في ExoPlayer، تحسين السرعة على الدقة في هذه الحالة وبالتالي، تكون الميزة FLAG_ENABLE_INDEX_SEEKING غير مفعّلة تلقائيًا.

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

لماذا يكون التقديم/الترجيع في الفيديو بطيئًا؟

عندما يحاول المشغّل الوصول إلى موضع تشغيل جديد في فيديو، يجب الانتقال إلى موضعَين جديدَين الأشياء:

  1. تحميل البيانات المقابلة لموضع التشغيل الجديد إلى المخزن المؤقت (قد لا يكون هذا ضروريًا إذا تم بالفعل تخزين هذه البيانات مؤقتًا).
  2. تفريغ برنامج فك ترميز الفيديو وبدء فك الترميز من الإطار الرئيسي I-frame (الإطار الرئيسي) قبل موضع التشغيل الجديد، وذلك بسبب الترميز داخل الإطار الذي تستخدمه معظم الفيديوهات وتنسيقات الضغط. لضمان أنّ عملية التقديم/الترجيع دقيقة (أي يبدأ التشغيل من موضع التقديم/الترجيع بالضبط)، وتبدأ جميع اللقطات بين يجب فك ترميز الإطار I السابق وموضع التقديم/الترجيع تم تجاهلها (بدون عرضها على الشاشة).

يمكن التخفيف من وقت الاستجابة الذي قدمه (1) إما عن طريق زيادة مقدار من البيانات التي خزّنها المشغّل في الذاكرة مؤقتًا، أو يخزّن البيانات مؤقتًا على قرص.

يمكن تخفيف وقت الاستجابة الذي ينتجه (2) إما عن طريق تقليل الدقة لتقديم الفيديو باستخدام ExoPlayer.setSeekParameters، أو إعادة ترميز الفيديو الحصول على إطارات I أكثر تكرارًا (مما سيؤدي إلى ملف إخراج أكبر).

لماذا يخفق تشغيل بعض ملفات MPEG-TS؟

لا تحتوي بعض ملفات MPEG-TS على محددات وحدة وصول (AUDs). بشكل افتراضي، يعتمد ExoPlayer على حسابات AUD لاكتشاف حدود الإطارات بتكلفة منخفضة. وبالمثل، فإن بعض لا تحتوي ملفات MPEG-TS على إطارات رئيسية لملفات IDR. بشكل افتراضي، تكون هذه هي النوع الوحيد الإطارات الرئيسية التي أخذتها ExoPlayer في الاعتبار

يبدو أن ExoPlayer عالق في حالة التخزين المؤقت عندما يُطلب منه تشغيل ملف MPEG-TS يفتقر إلى الإطارات الرئيسية AUD أو IDR إذا كنت بحاجة إلى تشغيل مثل هذه الملفات، يمكنك إجراء ذلك باستخدام FLAG_DETECT_ACCESS_UNITS FLAG_ALLOW_NON_IDR_KEYFRAMES على التوالي يمكن وضع هذه العلامات على DefaultExtractorsFactory باستخدام setTsExtractorFlags أو على DefaultHlsExtractorFactory باستخدام أداة الإنشاء: ليس لاستخدام FLAG_DETECT_ACCESS_UNITS أي آثار جانبية غير كونه مكلفة من الناحية الحاسوبية مقارنةً برصد حدود الإطار استنادًا إلى طريقة الدفع الأسترالي. استخدام قد يؤدي FLAG_ALLOW_NON_IDR_KEYFRAMES إلى تلف مرئي مؤقت في مباشرةً بعد البحث عند تشغيل بعض ملفات MPEG-TS.

لماذا لا يتم العثور على الترجمة في بعض ملفات MPEG-TS؟

تحتوي بعض ملفات MPEG-TS على مقاطع CEA-608 ولكن لا تذكرها في البيانات الوصفية للحاويات، لذا يتعذَّر على ExoPlayer رصدها. يمكنك يدويًا تحديد أي مقاطع الترجمة والشرح من خلال توفير قائمة تنسيقات العناوين الفرعية في DefaultExtractorsFactory، بما في ذلك أدوات تسهيل الاستخدام القنوات التي يمكن استخدامها لتحديدها في تدفق MPEG-TS:

Kotlin

val extractorsFactory =
  DefaultExtractorsFactory()
    .setTsSubtitleFormats(
      listOf(
        Format.Builder()
          .setSampleMimeType(MimeTypes.APPLICATION_CEA608)
          .setAccessibilityChannel(accessibilityChannel)
          // Set other subtitle format info, such as language.
          .build()
      )
    )
val player: Player =
  ExoPlayer.Builder(context, DefaultMediaSourceFactory(context, extractorsFactory)).build()

Java

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory()
        .setTsSubtitleFormats(
            ImmutableList.of(
                new Format.Builder()
                    .setSampleMimeType(MimeTypes.APPLICATION_CEA608)
                    .setAccessibilityChannel(accessibilityChannel)
                    // Set other subtitle format info, such as language.
                    .build()));
Player player =
    new ExoPlayer.Builder(context, new DefaultMediaSourceFactory(context, extractorsFactory))
        .build();

لماذا يتم تشغيل بعض ملفات MP4/FMP4 بشكل غير صحيح؟

تحتوي بعض ملفات MP4/FMP4 على قوائم تعديل تُعيد كتابة المخطط الزمني للوسائط من خلال أو تخطي قوائم العينات أو تحريكها أو تكرارها. ExoPlayer لديه دعم جزئي لتطبيق قوائم التعديل على سبيل المثال، قد يؤخر أو تكرار مجموعات من العينات في عينة مزامنة، لكنه لا يقتطع العيّنات الصوتية أو وسائط ما قبل التشغيل للتعديلات التي لا تبدأ في عينة المزامنة.

إذا كنت ترى هذا الجزء من الوسائط مفقود أو متكرر بشكل غير متوقع، جرِّب ضبط Mp4Extractor.FLAG_WORKAROUND_IGNORE_EDIT_LISTS أو FragmentedMp4Extractor.FLAG_WORKAROUND_IGNORE_EDIT_LISTS، والذي سيؤدي إلى أداة الاستخراج لتجاهل قوائم التعديل تمامًا. يمكن تعيينها على DefaultExtractorsFactory باستخدام setMp4ExtractorFlags أو setFragmentedMp4ExtractorFlags

لماذا يتعذّر اجتياز بعض عمليات البث عند ظهور رمز استجابة HTTP 301 أو 302؟

يشير كل من رمزي استجابة HTTP 301 و302 إلى إعادة التوجيه. أوصاف موجزة على ويكيبيديا. عندما يقدّم ExoPlayer طلبًا ويتلقّى برمز الحالة 301 أو 302، فسيتبع عادةً عملية إعادة التوجيه وبدء التشغيل كالمعتاد الحالة التي لا يحدث فيها هذا بشكل افتراضي لعمليات إعادة التوجيه عبر البروتوكولات. إعادة التوجيه عبر البروتوكولات هي عملية إعادة توجيه من HTTPS إلى HTTP أو العكس (أو الأقل شيوعًا بين زوج آخر من والبروتوكولات الأخرى). يمكنك اختبار ما إذا كان عنوان URL يتسبب في إعادة التوجيه عبر البروتوكولات أم لا باستخدام أداة سطر الأوامر wget على النحو التالي:

wget "https://yourserver.com/test.mp3" 2>&1  | grep Location

من المفترض أن تبدو النتيجة على النحو التالي:

Location: https://second.com/test.mp3 [following]
Location: http://third.com/test.mp3 [following]

في هذا المثال، هناك عمليتَا إعادة توجيه. عملية إعادة التوجيه الأولى من https://yourserver.com/test.mp3 إلى https://second.com/test.mp3 كلاهما بروتوكول HTTPS، وبالتالي ليست عملية إعادة توجيه عبر البروتوكولات. عملية إعادة التوجيه الثانية هي من https://second.com/test.mp3 إلى http://third.com/test.mp3 عملية إعادة التوجيه هذه من HTTPS إلى HTTP وكذلك إعادة التوجيه عبر البروتوكولات. لن يتمكن ExoPlayer من اتباع عملية إعادة التوجيه هذه في إعدادها التلقائي، ما يعني تعذّر التشغيل.

إذا احتجت إلى ذلك، يمكنك إعداد ExoPlayer لاتّباع عمليات إعادة التوجيه عبر البروتوكولات. عند إنشاء مثيل DefaultHttpDataSource.Factory لمثيل مستخدَم في التطبيق. مزيد من المعلومات عن اختيار حزمة الشبكة وضبطها هنا.

لماذا يتعذّر إكمال بعض مجموعات البث بسبب UnknownInputFormatException؟

يتعلق هذا السؤال بتعذُّر تشغيل النموذج التالي:

UnrecognizedInputFormatException: None of the available extractors
(MatroskaExtractor, FragmentedMp4Extractor, ...) could read the stream.

هناك سببان محتملان لهذا الإخفاق. السبب الأكثر شيوعًا هو كنت تحاول تشغيل DASH (mpd) أو HLS (m3u8) أو SmoothStreaming (ism أو isml) ولكن يجب أن يحاول اللاعب تشغيله كبثّ تدريجي. لتشغيل مثل عمليات البث، عليك الاعتماد على وحدة ExoPlayer المعنيّة. في الحالات التي عنوان URI للبث لا ينتهي بامتداد الملف القياسي، يمكنك أيضًا تمرير MimeTypes.APPLICATION_MPD أو MimeTypes.APPLICATION_M3U8 أو MimeTypes.APPLICATION_SS إلى setMimeType من إجمالي MediaItem.Builder بشكل صريح لتحديد نوع البث.

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

لماذا لا تعمل الدالة setPlayback parameters بشكل صحيح على بعض الأجهزة؟

عند تشغيل إصدار تصحيح أخطاء تطبيقك على Android M والإصدارات الأقدم، يمكنك: في تجربة الأداء المتقطّع والأصوات المسموعة واستخدام وحدة المعالجة المركزية (CPU) بشكل كبير باستخدام setPlaybackParameters API. ويرجع ذلك إلى أنّ التحسين بالنسبة إلى واجهة برمجة التطبيقات هذه، تم إيقافها بسبب إصدارات تصحيح الأخطاء التي تعمل على من Android.

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

ماذا يعني "تم الوصول إلى المشغّل في سلسلة محادثات غير صحيحة"؟ الأخطاء تعني؟

راجِع ملاحظة عن سلاسل المحادثات في صفحة البدء.

كيف يمكنني إصلاح "خط الحالة غير متوقع: ICY 200 OK"؟

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

كيف يمكنني معرفة ما إذا كان البث الذي يتم تشغيله بثًا مباشرًا؟

يمكنك طلب البحث عن طريقة المشغّل isCurrentWindowLive. بالإضافة إلى ذلك، يمكنه التحقّق من isCurrentWindowDynamic لمعرفة ما إذا كانت النافذة ديناميكية. (أي لا يزال يتم تعديلها بمرور الوقت).

كيف يمكنني مواصلة تشغيل الصوت عندما يكون تطبيقي في الخلفية؟

اتّبِع هذه الخطوات لضمان استمرار تشغيل الصوت عندما يكون تطبيقك قيد التشغيل. الخلفية:

  1. يجب أن يكون لديك خدمة تعمل في المقدّمة. يمنع هذا النظام من إنهاء العملية لتحرير الموارد.
  2. يجب تثبيت WifiLock وWakeLock. وهي تضمن أن يحافظ على تنشيط راديو WiFi ووحدة المعالجة المركزية (CPU). يمكن القيام بذلك بسهولة إذا كنت تستخدم ExoPlayer عن طريق الاتصال بالرقم setWakeMode، والذي سيتم تلقائيًا الحصول على الأقفال المطلوبة وتحريرها في الأوقات الصحيحة.

من المهم فتح الأقفال (في حال عدم استخدام setWakeMode) وإيقافها الخدمة فور التوقّف عن تشغيل الصوت.

لماذا تتوافق منصة ExoPlayer مع المحتوى الخاص بي ولا تتوافق مكتبة ExoPlayer Cast مع ذلك؟

من المحتمل أنّ المحتوى الذي تحاول تشغيله غير تفعيل سياسة مشاركة الموارد المتعددة المصادر (CORS). يتطلب إطار عمل Cast تفعيل سياسة مشاركة الموارد المتعددة المصادر (CORS) في المحتوى في لتشغيلها.

لماذا يتعذّر تشغيل المحتوى بدون ظهور أي خطأ؟

من المحتمل أنّ الجهاز الذي تشغّل المحتوى عليه تتيح استخدام تنسيق معيّن من الوسائط ويمكن التأكد من ذلك بسهولة عن طريق إضافة EventLogger كمستمِع إلى المشغّل ويبحث عن خطّ مشابهة لتلك في Logcat:

[ ] Track:x, id=x, mimeType=mime/type, ... , supported=NO_UNSUPPORTED_TYPE

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

كيف يمكنني تحميل مكتبة لفك الترميز واستخدامها في التشغيل؟

  • تحتوي معظم مكتبات فك الترميز على خطوات يدوية للتحقق من التبعيات وإنشاءها، لذلك تأكد من اتباعك الخطوات الموجودة في الملف التمهيدي للمكتبة ذات الصلة. على سبيل المثال، بالنسبة إلى مكتبة ExoPlayer FFmpeg، من الضروري اتباع التعليمات في libraries/decoder_ffmpeg/README.md، بما في ذلك اجتياز علامات الضبط لتفعيل برامج فك الترميز لأي تنسيقات تريد تشغيلها.
  • بالنسبة إلى المكتبات التي تتضمّن رمزًا أصليًا، احرص على استخدام الترميز الصحيح من Android NDK كما هو محدد في الملف التمهيدي، وابحث عن أي التي تظهر أثناء التكوين والإنشاء. من المفترض أن يظهر لك .so من الملفات في الدليل الفرعي libs من مسار المكتبة لكل ملف بنية مدعومة بعد اتباع الخطوات الواردة في الملف التمهيدي.
  • لتجربة التشغيل باستخدام المكتبة في التطبيق التجريبي، يُرجى الاطّلاع على تفعيل برامج فك الترميز المجمّعة اطّلع على الملف التمهيدي للمكتبة التعليمات حول استخدام المكتبة من تطبيقك.
  • إذا كنت تستخدم DefaultRenderersFactory، من المفترض أن يظهر لك مستوى المعلومات. سطر السجل مثل "Loaded FfmpegAudioRenderer" في Logcat عند تحميل برنامج فك الترميز. وإذا كان ذلك مفقودًا، فتأكد من أن التطبيق يعتمد على مكتبة فك الترميز.
  • إذا ظهرت لك سجلّات على مستوى التحذير من LibraryLoader في Logcat، سيؤدي هذا الإجراء إلى إلى فشل تحميل المكون الأصلي للمكتبة. إذا كان هذا ونتحقق من أنك اتبعت الخطوات الواردة في الملف التمهيدي الخاص بالمكتبة بشكل صحيح. وأنه لم يتم العثور على أي أخطاء أثناء اتباع التعليمات.

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

هل يمكنني تشغيل فيديوهات YouTube مباشرةً باستخدام ExoPlayer؟

لا، لا يمكن لـ ExoPlayer تشغيل فيديوهات من YouTube، مثل عناوين URL للنموذج https://www.youtube.com/watch?v=... بدلاً من ذلك، يجب استخدام صفحة YouTube IFrame Player API وهي الطريقة الرسمية لتشغيل فيديوهات YouTube على Android.

هناك تقطُّع في تشغيل الفيديو

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

في حال ظهور تقطُّع في الفيديو على جهاز يعمل بإصدار Android بدءًا من الإصدار Android 6.0 (المستوى 23 لواجهة برمجة التطبيقات) وحتى الإصدار Android 11 (المستوى 30 لواجهة برمجة التطبيقات) لا سيما عند تشغيل محتوى محمي بموجب إدارة الحقوق الرقمية أو بمعدل إطارات عالٍ، فيمكنك تجربة تفعيل المخزن المؤقت غير المتزامن في قائمة الانتظار.

أخطاء أداة Lint غير الثابتة لواجهة برمجة التطبيقات

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

إنّ التعليق التوضيحي @UnstableApi لا يشير ضمنًا إلى جودة واجهة برمجة التطبيقات أو أدائها، بل يشير فقط إلى أنّ التعليق التوضيحي ليس "متوقفًا عن واجهة برمجة التطبيقات".

لديك خياران لمعالجة أخطاء أداة Lint غير الثابتة لواجهة برمجة التطبيقات:

  • يمكنك التبديل إلى استخدام واجهة برمجة تطبيقات ثابتة تحقّق النتيجة نفسها.
  • يمكنك مواصلة استخدام واجهة برمجة التطبيقات غير الثابتة وإضافة تعليقات توضيحية إلى بيانات الاستخدام من خلال @OptIn، مثل سيظهر لاحقًا.
إضافة التعليق التوضيحي "@OptIn"

يمكن أن يساعدك "استوديو Android" في إضافة التعليق التوضيحي:

لقطة شاشة: كيفية إضافة التعليق التوضيحي لتفعيل الميزة
الشكل 2: إضافة التعليق التوضيحي @androidx.annotations.OptIn باستخدام "استوديو Android".

يمكنك أيضًا إضافة تعليقات توضيحية يدويًا إلى مواقع استخدام محددة في Kotlin:

import androidx.annotation.OptIn
import androidx.media3.common.util.UnstableApi

@OptIn(UnstableApi::class)
fun functionUsingUnstableApi() { ... }

وأيضًا في Java:

import androidx.annotation.OptIn;
import androidx.media3.common.util.UnstableApi;

@OptIn(markerClass = UnstableApi.class)
private void methodUsingUnstableApis() { ... }

يمكن تفعيل الحِزم بالكامل من خلال إضافة ملف package-info.java:

@OptIn(markerClass = UnstableApi.class)
package name.of.your.package;

import androidx.annotation.OptIn;
import androidx.media3.common.util.UnstableApi;

يمكن تمكين المشروعات بأكملها من خلال منع خطأ الوبر المحدد في ملف واحد (lint.xml):

 <?xml version="1.0" encoding="utf-8"?>
 <lint>
   <issue id="UnsafeOptInUsageError">
     <option name="opt-in" value="androidx.media3.common.util.UnstableApi" />
   </issue>
 </lint>

هناك أيضًا تعليق توضيحي kotlin.OptIn يجب عدم استخدامه. من المهم استخدام تعليق androidx.annotation.OptIn التوضيحي.