beagle

بيغل (مكتبة أندرويد)

مكتبة قائمة تصحيح ذكية وموثوقة وقابلة للتخصيص للغاية لتطبيقات Android التي تدعم تسجيل الشاشة وتسجيل نشاط الشبكة وإنشاء تقارير الأخطاء والعديد من الميزات المفيدة الأخرى.

الخطوات الأولى

أراه في العمل

استنساخ هذا المستودع ، واختر البديل البديل وقم بتشغيل تكوين التطبيق . يجب أن تبدو مثل هذا:

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

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

استخدمه في مشروعك

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

الخطوة 0: تحقق من المتطلبات

• الحد الأدنى لمستوى SDK: 24+
• مستوى SDK الهدف: 34+ (تحقق من الإصدارات القديمة للهدف SDK-S)

الخطوة 1: أضف مستودع Mavencentral

تأكد من أن ما يلي جزء من ملف build.gradle على مستوى المشروع:

allprojects {
    repositories {
        …
        mavenCentral()
    }
}

الخطوة 2: اختر تطبيق واجهة المستخدم وتكوين التبعيات

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

• نشاط واجهة المستخدم - يعرض قائمة التصحيح على أنها شاشة جديدة (غير موصى بها: الوسائط أكثر فائدة).
• ui-bottom sheet- يعرض قائمة تصحيح الأخطاء كورقة قاعّة مشروطة (موصى بها).
• UI -Dialog - يعرض قائمة التصحيح كمربع حوار وسيط (موصى به).
• UI -Drawer - يعرض قائمة التصحيح كدرج تنقل جانبي (موصى به للغاية).
• UI -View - عرض DebugMenuView هو مسؤوليتك (غير مستحسن: Shake to Open ، Beagle.show() ، Beagle.hide() ، لن ينجح VisibilityListener ذات الصلة بالإضافة إلى منطق معالجة أقحم من الصندوق).
• noop - لا واجهة المستخدم ، لا منطق. لديها نفس واجهة برمجة التطبيقات العامة مثل جميع المتغيرات الأخرى ، لكنها لا تفعل شيئًا (هذا مخصص لبناء الإنتاج).

لذلك ، على سبيل المثال ، إذا كنت تفضل واجهة مستخدم الدرج ، فسيحتاج شيء مثل ما يلي إلى إضافته إلى ملف Build.gradle على مستوى التطبيق (تحقق من عنصر واجهة المستخدم أسفل قصاصة الرمز للحصول على أحدث إصدار):

dependencies {
    …
    def beagleVersion = " 2.9.8 "
    debugImplementation " io.github.pandulapeter.beagle:ui-drawer: $b eagleVersion "
    releaseImplementation " io.github.pandulapeter.beagle:noop: $b eagleVersion "
}

أحدث إصدار هو:

ملاحظة : في حالة واجهة المستخدم الدرج ، إذا قمت بإعداد طريقة Overted the Activity onBackPressed() ، فقد تلاحظ أن معالجة التنقل الافتراضي الافتراضي لا تعمل دائمًا كما هو متوقع. لإصلاح هذا ، في كل Activity onBackPressed() يجب عليك التحقق من أن Beagle.hide() يعيد خطأ قبل إجراء أي شيكات أخرى أو استدعاء التنفيذ الفائق.

الخطوة 3: تهيئة المكتبة

سطر واحد فقط من التعليمات البرمجية ، ويفضل أن يكون ذلك في طريقة onCreate() Application :

 Beagle .initialize( this )

اختياريا يمكنك إضافة المعلمات التالية إلى هذه الوظيفة:

• يمكن تخصيص ظهور القائمة من خلال تحديد مثيل المظهر. على سبيل المثال ، هنا يمكنك تحديد سمة مخصصة لقائمة التصحيح باستخدام خاصية themeResourceId ، في حالة عدم مناسب Application / Activity . ملاحظة: من المستحسن تمديد موضوع المواد .NoActionBar .
• يمكن تخصيص سلوك القائمة من خلال تحديد مثيل سلوك. على سبيل المثال ، يعد ضبط الهز على العتبة المفتوحة أو قوة التعليقات الباهتة حالة استخدام متكررة في هذه الفئة.

بشكل افتراضي ، يمكنك جلب Beagle عن طريق هز الجهاز.

الخطوة 4: إنهاء الإعداد عن طريق إضافة وحدات

بعد هذا ، يجب توفير عدد من الوحدات ، ولكن يمكن تغيير هذا التكوين في أي وقت (من أي مؤشر ترابط) وسيتم تحديث واجهة المستخدم تلقائيًا. أبسط طريقة للقيام بذلك هي الاتصال:

 Beagle .set(module1, module2, …)

في هذه المرحلة ، يجب أن تكون على دراية بخيارين:

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

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

فيما يلي مثال بسيط يجب أن يعمل لمعظم المشاريع:

 Beagle .set(
    HeaderModule (
        title = getString( R .string.app_name),
        subtitle = BuildConfig . APPLICATION_ID ,
        text = " ${ BuildConfig . BUILD_TYPE } v ${ BuildConfig . VERSION_NAME } ( ${ BuildConfig . VERSION_CODE } ) "
    ),
    AppInfoButtonModule (),
    DeveloperOptionsButtonModule (),
    PaddingModule (),
    TextModule ( " General " , TextModule . Type . SECTION_HEADER ),
    KeylineOverlaySwitchModule (),
    AnimationDurationSwitchModule (),
    ScreenCaptureToolboxModule (),
    DividerModule (),
    TextModule ( " Logs " , TextModule . Type . SECTION_HEADER ),
    NetworkLogListModule (), // Might require additional setup, see below
    LogListModule (), // Might require additional setup, see below
    LifecycleLogListModule (),
    DividerModule (),
    TextModule ( " Other " , TextModule . Type . SECTION_HEADER ),
    DeviceInfoModule (),
    BugReportButtonModule ()
)

إذا كنت بحاجة إلى إضافة وحدات مؤقتة ، Beagle.add() لديها معلمة اختيارية lifecycleOwner التي تزيل الوحدات النمطية المحددة تلقائيًا بمجرد انتهاء دورة الحياة المقدمة. يعد الاتصال يدويًا Beagle.remove() مع وحدة ID-S خيارًا أيضًا.

ميزات متقدمة

قطع الأشجار

على الرغم من أن الاتصال Beagle.log() هو أبسط طريقة لإضافة عناصر إلى LogListModule ، إلا أن هناك حاجة إلى حل خاص للوصول إلى هذه الوظيفة من وحدات Kotlin النقية. حالة الاستخدام المتكررة الأخرى هي التكامل مع الأخشاب.

تسجيل من وحدات Kotlin النقية

للوصول إلى نفس الوظيفة التي يوفرها Beagle.log() من وحدة Kotlin / Java النقية ، تحتاج أولاً إلى إضافة ما يلي إلى الوحدة المعنية:

dependencies {
    …
    api " io.github.pandulapeter.beagle:log: $b eagleVersion "

    // Alternative for Android modules:
    // debugApi "io.github.pandulapeter.beagle:log:$beagleVersion"
    // releaseApi "io.github.pandulapeter.beagle:log-noop:$beagleVersion"
}

توفر هذه المكتبات كائن BeagleLogger الذي يجب توصيله بالمكتبة الرئيسية عند تهيئته في فئة Application :

 Beagle .initialize(
    …
    behavior = Behavior (
        …
        logBehavior = Behavior . LogBehavior (
            loggers = listOf ( BeagleLogger ),
            …
        )
    )
)

لإضافة رسائل سجل ، يمكنك الآن الاتصال بما يلي:

 BeagleLogger .log(…)

سيتم دمج قائمة الرسائل مع تلك التي تم تسجيلها باستخدام وظيفة Beagle.log() العادية (ما لم يتم ترشيحها بواسطة علاماتها) ويمكن عرضها باستخدام قائمة تسجيل الدخول. يمكنك أيضًا استخدام BeagleLogger.clearLogEntries() إذا لم تتمكن من الوصول إلى Beagle.clearLogEntries() .

تسجيل مع الأخشاب

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

 Timber .plant(
    object : Timber . Tree () {
        override fun log ( priority : Int , tag : String? , message : String , t : Throwable ? ) =
            Beagle .log( " [ $tag ] $message " , " Timber " , t?.stackTraceToString())
    }
)

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

اعتراض أحداث الشبكة

لا يتم تجميع اعتراض الشبكة مع المكتبة الرئيسية بشكل أساسي لتوفير تبعية Kotlin النقية التي لا تستخدم Android SDK ، على غرار حل المسجل الموضح أعلاه. في الوقت الحالي ، لا يمكن لـ Beagle ربط مكتبة شبكات OKHTTP لتوفير محتوى لـ NetworkLogListModule ، ولكن الاتصال يدويًا Beagle.logNetworkEvent() هو دائمًا خيار.

أضف ما يلي إلى الوحدة النمطية حيث يتم تنفيذ منطق الشبكات الخاص بك:

dependencies {
    …
    api " io.github.pandulapeter.beagle:log-okhttp: $b eagleVersion "
    
    // Alternative for Android modules:
    // debugApi "io.github.pandulapeter.beagle:log-okhttp:$beagleVersion"
    // releaseApi "io.github.pandulapeter.beagle:log-okhttp-noop:$beagleVersion"
}

سيؤدي ذلك إلى تقديم كائن BeagleOkHttpLogger الذي يحتاج أولاً إلى توصيل المكتبة الرئيسية ، في اللحظة التي يتم فيها تهيئة:

 Beagle .initialize(
    …
    behavior = Behavior (
        …
        networkLogBehavior = Behavior . NetworkLogBehavior (
            networkLoggers = listOf ( BeagleOkHttpLogger ),
            …
        )
    )
)

تتمثل الخطوة الأخيرة في إعداد Interceptor (الصب الحراري موجود للتأكد من أن تطبيق NOOP لا يفعل شيئًا بينما لا يزال لديه نفس واجهة برمجة التطبيقات العامة):

 val client = OkHttpClient . Builder ()
    …
    . apply { ( BeagleOkHttpLogger .logger as ? Interceptor ? )?. let { addInterceptor(it) } }
    .build()

عرض سجلات التحطم

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

dependencies {
    …
    debugImplementation " io.github.pandulapeter.beagle:log-crash: $b eagleVersion "
    releaseImplementation " io.github.pandulapeter.beagle:log-crash-noop: $b eagleVersion "
}

بعد إضافة التبعيات ، يجب توصيل كائن BeagleCrashLogger الذي تم تقديمه حديثًا بالمكتبة الرئيسية:

 Beagle .initialize(
    …
    behavior = Behavior (
        …
        bugReportingBehavior = Behavior . BugReportingBehavior (
            crashLoggers = listOf ( BeagleCrashLogger ),
            …
        )
    )
)

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

أيضًا ، يرجى ملاحظة أنه من خلال تقديم تبعية log-crash ، سيتم تشغيل نشاط الإبلاغ عن أخطاء Beagle الآن في عملية منفصلة (على سبيل المثال ، يحتاج Firebase إلى استدعاء التهيئة التخصصية لتطبيقات متعددة العمليات).

تحسين التغليف

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

• المزايا
  • لا يوجد بيغل يستورد خارج وحدة الغلاف
  • وجود نقطة دخول واحدة لجميع الميزات المتعلقة بقائمة التصحيح
• عيوب
  • المزيد من الإعداد الأولي مرهقة
  • فقدان القدرة على استخدام ميزات بيغل في وحدات كوتلين النقية

استكشاف الأخطاء وإصلاحها

لا يظهر واجهة مستخدم قائمة التصحيح

• تأكد من أنك لا تستخدم قطعة أثرية noop في تكوينك الحالي
• تأكد من استدعاء وظيفة initialize() في فئة Application المخصصة ، وأن الفئة مسجلة بشكل صحيح في البيان
• تأكد من أن نشاطك يمتد FragmentActivity (على سبيل المثال ، AppCompatActivity هو خيار جيد). احترس من ذلك ، إذا كنت تستخدم قالب Empty Compose Activity من Android Studio ، فيجب عليك تغيير فئة Parent Default!

تحطم في إطلاق التطبيق

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

تحطم عند فتح نشاط طرف ثالث

يعمل Beagle عن طريق إضافة Fragment أعلى من تصميم كل Activity . في بعض الأحيان لا يكون هذا ضروريًا أو غير ممكن. بينما تأتي المكتبة مع قائمة بأسماء حزم Activity المستبعدة ، يمكنك توفير تصفية إضافية إذا لزم الأمر ، باستخدام خاصية shouldAddDebugMenu lambda لمثيل السلوك المقدم أثناء التهيئة.

معرض أو شاشات تقرير الأخطاء التي تحتوي على أشرطة أدوات

قم بتعيين موضوع المواد .NoActionBar لخاصية themeResourceId لمثيل المظهر المقدم أثناء التهيئة.

عن

الوثائق

تم توثيق جميع الوظائف العامة مع KDOC. يعد ملف Beglecontract بداية جيدة للتعرف على جميع القدرات المدمجة. للحصول على معلومات حول الوحدات النمطية الفردية ، راجع رؤوس الفصل ذات الصلة.

إذا كنت مهتمًا بما هو تحت الغطاء ، فقد يكون هذا المستند مفيدًا أثناء التنقل في رمز المصدر.

Changelog

تحقق من صفحة الإصدارات للتغييرات في كل إصدار.

تستخدم المكتبة الإصدار الدلالي: major.minor.patch حيث تتغير التصحيح فقط تحتوي على إصلاحات الأخطاء ، وتضيف التغييرات البسيطة ميزات جديدة وتغييرات رئيسية تقدم تعديلات كسر في واجهة برمجة التطبيقات.

القضايا المعروفة

تحقق من صفحة المشكلات للحصول على قائمة المشكلات المعروفة والتحسينات المخطط لها للمكتبة.

لا تتردد في فتح مشكلة جديدة إذا وجدت خطأ أو إذا كان لديك أي أسئلة / طلبات ميزة!

اشتر لي بيرة

إذا وجدت عملي مفيدًا وتفكر في تبرع صغير ، فإن قسم About من تطبيق العرض لديه خيار لك للقيام بذلك. شكرا مقدما!

رخصة

 Copyright 2022 Pandula Péter

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.