beagle

Beagle (ห้องสมุด Android)

ไลบรารีเมนูดีบั๊กที่ฉลาดเชื่อถือได้และปรับแต่งได้สูงสำหรับแอพ Android ที่รองรับการบันทึกหน้าจอการบันทึกกิจกรรมเครือข่ายการสร้างรายงานข้อผิดพลาดและคุณสมบัติที่มีประโยชน์อื่น ๆ อีกมากมาย

ขั้นตอนแรก

เห็นมันในการดำเนินการ

โคลนที่เก็บนี้เลือกตัวแปรบิลด์และเรียกใช้การกำหนดค่า แอป มันควรจะดูอะไรแบบนี้:

แอปพลิเคชันตัวอย่างนี้ยังมีคำแนะนำเกี่ยวกับวิธีการตั้งค่า Beagle และวิธีการใช้คุณสมบัติต่าง ๆ ที่กำลังจัดแสดง คุณควรพิจารณาลองใช้ลองถ้าคุณสนใจที่จะใช้ห้องสมุดในโครงการของคุณ หากคุณไม่รู้สึกอยากสร้างด้วยตัวคุณเองคุณสามารถดาวน์โหลดได้จาก Play Store:

บทช่วยสอนในแอพครอบคลุมทุกอย่างจาก readme นี้ แต่ในรายละเอียดเพิ่มเติม อีกวิธีหนึ่งที่จะได้รับความคิดเกี่ยวกับสิ่งที่สามารถทำได้ด้วยห้องสมุดคือบทความนี้ซึ่งนำเสนอปัญหาต่าง ๆ ที่สามารถแก้ไขได้ด้วยบีเกิ้ล

ใช้ในโครงการของคุณ

หากผนังข้อความด้านล่างยาวเกินไปสำหรับรสนิยมของคุณลองดูที่สำคัญนี้ที่มีรหัสทั้งหมดที่คุณต้องการสำหรับการกำหนดค่าที่ดี มิฉะนั้นมาทำทีละขั้นตอน:

ขั้นตอนที่ 0: ตรวจสอบข้อกำหนด

• ระดับ SDK ขั้นต่ำ: 24+
• เป้าหมาย SDK Target: 34+ (ตรวจสอบรุ่นเก่าสำหรับเป้าหมาย SDK-S ที่เล็กกว่า)

ขั้นตอนที่ 1: เพิ่มที่เก็บ mavencentral

ตรวจสอบให้แน่ใจว่าต่อไปนี้เป็นส่วนหนึ่งของไฟล์ build.gradle ระดับโครงการของคุณ:

allprojects {
    repositories {
        …
        mavenCentral()
    }
}

ขั้นตอนที่ 2: เลือกการใช้งาน UI และกำหนดค่าการอ้างอิง

UI ที่แท้จริงของเมนูการดีบักสามารถแสดงได้หลายวิธีซึ่งระบุโดยคำต่อท้ายของการพึ่งพา มีเวอร์ชันต่อไปนี้:

• ui -activity - แสดงเมนูการดีบักเป็นหน้าจอใหม่ (ไม่แนะนำ: โมดาลมีประโยชน์มากกว่า)
• UI-BOTTOM-SHEET- แสดงเมนูการดีบักเป็นแผ่นด้านล่างแบบโมดัล (แนะนำ)
• UI -DIALOG - แสดงเมนูการดีบักเป็นกล่องโต้ตอบแบบโมดอล (แนะนำ)
• UI -DRAWER - แสดงเมนูการดีบักเป็นลิ้นชักนำทางด้านข้าง (แนะนำเป็นอย่างยิ่ง)
• UI -View - การแสดง DebugMenuView เป็นความรับผิดชอบของคุณ (ไม่แนะนำ: Shake to Open, Beagle.show() , Beagle.hide() , VisibilityListener ที่เกี่ยวข้องและตรรกะการจัดการสิ่งที่ใส่เข้าไปจะไม่ทำงานนอกกรอบ)
• Noop - ไม่มี UI ไม่มีตรรกะ มันมี API สาธารณะเช่นเดียวกับตัวแปรอื่น ๆ ทั้งหมด แต่มันไม่ได้ทำอะไรเลย

ตัวอย่างเช่นหากคุณต้องการลิ้นชัก UI สิ่งต่าง ๆ เช่นไฟล์ต่อไปนี้จะต้องเพิ่มลงในไฟล์ 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 "
}

เวอร์ชันล่าสุดคือ:

หมายเหตุ : ในกรณีของลิ้นชัก UI หากคุณได้เขียนทับวิธี onBackPressed() ของ Activity คุณอาจสังเกตเห็นว่าการจัดการการนำทางกลับเริ่มต้นไม่ได้ผลตามที่คาดไว้เสมอไป ในการแก้ไขปัญหานี้ในทุก Activity onBackPressed() คุณควรตรวจสอบว่า Beagle.hide() ส่งคืนเท็จก่อนทำการตรวจสอบอื่น ๆ หรือเรียกใช้การใช้งาน Super

ขั้นตอนที่ 3: เริ่มต้นไลบรารี

เพียงหนึ่งบรรทัดของรหัสโดยเฉพาะอย่างยิ่งในวิธี onCreate() ของ Application :

 Beagle .initialize( this )

คุณสามารถเพิ่มพารามิเตอร์ต่อไปนี้ลงในฟังก์ชั่นนี้:

• ลักษณะที่ปรากฏของเมนูสามารถปรับให้เป็นส่วนตัวได้โดยการระบุอินสแตนซ์ลักษณะที่ปรากฏ ตัวอย่างเช่นที่นี่คุณสามารถระบุธีมที่กำหนดเองสำหรับเมนูดีบั๊กโดยใช้คุณสมบัติ themeResourceId ในกรณีที่ Application / Activity ที่ใช้ไม่เหมาะสม หมายเหตุ: ขอแนะนำให้ขยายชุดรูปแบบวัสดุ .NoActionBar
• พฤติกรรมของเมนูสามารถทำให้เป็นส่วนตัวได้โดยการระบุอินสแตนซ์พฤติกรรม ตัวอย่างเช่นการปรับการเขย่าเพื่อเปิดเกณฑ์หรือความแข็งแรงของข้อเสนอแนะแบบสัมผัสเป็นกรณีการใช้งานบ่อยครั้งของคลาสนี้

โดยค่าเริ่มต้นคุณสามารถดึงบีเกิ้ลได้โดยการเขย่าอุปกรณ์

ขั้นตอนที่ 4: เสร็จสิ้นการตั้งค่าโดยการเพิ่มโมดูล

หลังจากนี้จำนวนโมดูลควรมีให้ แต่การกำหนดค่านี้สามารถเปลี่ยนแปลงได้ตลอดเวลา (จากเธรดใด ๆ ) และ UI จะได้รับการอัปเดตโดยอัตโนมัติ วิธีที่ง่ายที่สุดในการทำเช่นนี้คือการโทร:

 Beagle .set(module1, module2, …)

ณ จุดนี้คุณควรทราบสองตัวเลือก:

• รายการโมดูลในตัว ทุกไฟล์ในแพ็คเกจนี้มีการบันทึกไว้ โมดูลเหล่านี้ควรครอบคลุมกรณีการใช้งานส่วนใหญ่และมีข้อได้เปรียบในการจัดหาการใช้งานของปลอมและไม่มีการใช้ Noop ซึ่งหมายความว่าไม่มีส่วนใดส่วนหนึ่งของตรรกะของพวกเขาที่รวบรวมไว้ในการสร้างของคุณ
• ความสามารถในการเขียนโมดูลที่กำหนดเอง สำหรับจุดเริ่มต้นที่ดีนี้คือการดูการใช้งานในตัวจากด้านบน แต่เอกสารนี้ยังให้คำแนะนำบางอย่าง

ตรวจสอบแอป Showcase สำหรับแนวคิดบางอย่างเกี่ยวกับสิ่งที่เป็นไปได้ด้วยโมดูลในตัวหรือสำหรับเครื่องมือแบบโต้ตอบที่สามารถใช้ในการดูตัวอย่างการกำหนดค่าโมดูลใด ๆ และสร้างรหัสสำหรับมัน คู่มือที่เป็นไปได้มากขึ้นเกี่ยวกับความเป็นไปได้บางอย่างคือบทความนี้

นี่คือตัวอย่างน้อยที่สุดที่ควรใช้งานได้สำหรับโครงการส่วนใหญ่:

 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() ปกติ (เว้นแต่ว่าพวกเขาจะถูกกรองด้วยแท็ก) และสามารถแสดงได้โดยใช้ loglistModule คุณยังสามารถใช้ 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())
    }
)

ในการสร้าง loglistmodule พิเศษที่แสดงเฉพาะบันทึกเหล่านี้เพียงตั้งค่าพารามิเตอร์ตัวสร้าง ฉลาก ของโมดูลเป็น "ไม้"

เหตุการณ์เครือข่ายที่สกัดกั้น

ไม่รวมการสกัดกั้นเครือข่ายกับห้องสมุดหลักส่วนใหญ่ทำเพื่อให้การพึ่งพา Kotlin บริสุทธิ์ที่ไม่ได้ใช้ Android SDK คล้ายกับโซลูชัน logger ที่อธิบายไว้ข้างต้น ในขณะที่ Beagle สามารถเชื่อมต่อกับ Okhttp Networking Library เพื่อให้เนื้อหาสำหรับ 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 ไม่ได้ทำอะไรในขณะที่ยังคงมี API สาธารณะเดียวกัน):

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

การแสดงบันทึกความผิดพลาด

ห้องสมุดสามารถสกัดกั้นข้อยกเว้นที่ไม่ถูกต้องและแสดงร่องรอยสแต็กของพวกเขาในกล่องโต้ตอบ ผู้ใช้จะสามารถแชร์รายงานข้อผิดพลาดโดยใช้หน้าจอการรายงานข้อผิดพลาดที่เปิดโดยอัตโนมัติ ฟังก์ชั่นนี้ทำได้ผ่านการพึ่งพาแยกต่างหากที่ควรเพิ่มเข้าไปในโมดูลหลัก (โดยที่ Beagle เริ่มต้น):

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 จะทำงานในกระบวนการแยกต่างหาก (ตัวอย่างเช่นการเรียกใช้การเริ่มต้นเป็นพิเศษสำหรับแอพหลายกระบวนการ)

การปรับปรุงการห่อหุ้ม

การใช้งาน noop ของสิ่งประดิษฐ์สาธารณะทุกชิ้นเป็นวิธีเริ่มต้นที่ไม่รวมตรรกะที่เกี่ยวข้องกับบีเกิ้ลในการผลิตของคุณ แม้ว่าสิ่งนี้จะดีพอสำหรับโครงการส่วนใหญ่สามารถปรับปรุงได้โดยการสร้างโมดูล wrapper แยกต่างหากสำหรับเมนูการดีบัก นี่หมายถึงการซ่อนการโทรทุกครั้งไปยัง Beagle หลังอินเทอร์เฟซที่มีการใช้งานที่ว่างเปล่าในการสร้างรุ่น วิธีการนี้มีประโยชน์และข้อเสียของตัวเอง:

• ข้อดี
  • ไม่มีบีเกิ้ลนำเข้าด้านนอกของโมดูล wrapper
  • มีจุดเข้าใช้เดียวสำหรับคุณสมบัติทั้งหมดที่เกี่ยวข้องกับเมนูการดีบัก
• ข้อเสีย
  • การตั้งค่าเริ่มต้นที่ยุ่งยากมากขึ้น
  • การสูญเสียความสามารถในการใช้คุณสมบัติ Beagle ในโมดูล Kotlin บริสุทธิ์

การแก้ไขปัญหา

เมนูดีบั๊ก UI ไม่ปรากฏขึ้น

• ตรวจสอบให้แน่ใจว่าคุณไม่ได้ใช้สิ่งประดิษฐ์ noop ในการกำหนดค่าปัจจุบันของคุณ
• ตรวจสอบให้แน่ใจว่าคุณเรียกฟังก์ชั่น initialize() ในคลาส Application ที่กำหนดเองของคุณและคลาสนั้นได้รับการลงทะเบียนอย่างถูกต้องในรายการ
• ตรวจสอบให้แน่ใจว่ากิจกรรมของคุณขยาย FragmentActivity (ตัวอย่างเช่น AppCompatActivity เป็นตัวเลือกที่ดี) ระวังถ้าคุณใช้เทมเพลต Empty Compose Activity ของ Android Studio คุณต้องเปลี่ยนคลาสแม่เริ่มต้น!

Crash on App Launch

โดยค่าเริ่มต้น Beagle ใช้ธีม Activity ปัจจุบัน อย่างไรก็ตามมันต้องใช้ชุดรูปแบบวัสดุในการทำงานดังนั้นหากคุณมีความผิดพลาดที่เกิดจากแอตทริบิวต์ชุดรูปแบบต่าง ๆ ที่ไม่พบคุณจะแทนที่ชุดรูปแบบของเมนูการดีบักด้วยคุณสมบัติ themeResourceId ของอินสแตนซ์ที่ปรากฏในระหว่างการเริ่มต้นด้วยชุดรูปแบบวัสดุ

เกิดความผิดพลาดเมื่อเปิดกิจกรรมของบุคคลที่สาม

Beagle ทำงานโดยการเพิ่ม Fragment ที่ด้านบนของเค้าโครงของทุก Activity บางครั้งสิ่งนี้ไม่จำเป็นหรือเป็นไปไม่ได้ ในขณะที่ไลบรารีมาพร้อมกับรายการชื่อแพ็คเกจ Activity ที่ยกเว้นคุณสามารถให้การกรองเพิ่มเติมได้หากจำเป็นโดยใช้คุณสมบัติ shouldAddDebugMenu แตนซ์พฤติกรรมที่ให้ไว้ในระหว่างการเริ่มต้น

หน้าจอแกลเลอรี่หรือข้อผิดพลาดมีแถบเครื่องมือสองแถบ

ตั้งค่าชุดรูปแบบวัสดุ .NoActionBar สำหรับคุณสมบัติ themeResourceId ของอินสแตนซ์ลักษณะที่ให้ไว้ในระหว่างการเริ่มต้น

เกี่ยวกับ

เอกสาร

ฟังก์ชั่นสาธารณะทั้งหมดได้รับการบันทึกด้วย KDOC ไฟล์ Beaglecontract เป็นการเริ่มต้นที่ดีสำหรับการเรียนรู้เกี่ยวกับความสามารถในตัวทั้งหมด สำหรับข้อมูลเกี่ยวกับแต่ละโมดูลดูส่วนหัวชั้นเรียนที่เกี่ยวข้อง

หากคุณสนใจสิ่งที่อยู่ภายใต้ประทุนเอกสารนี้จะเป็นประโยชน์ในขณะที่นำทางซอร์สโค้ด

การเปลี่ยนแปลง

ตรวจสอบหน้ารีลีสสำหรับการเปลี่ยนแปลงในทุกเวอร์ชัน

ไลบรารีใช้การกำหนดเวอร์ชันความหมาย: major.minor.patch ที่การเปลี่ยนแปลง แพตช์ มีเฉพาะการแก้ไขข้อผิดพลาดการเปลี่ยนแปลง เล็กน้อย เพิ่มคุณสมบัติใหม่และการเปลี่ยนแปลง ที่สำคัญ แนะนำการปรับเปลี่ยนการเปลี่ยนแปลงไปยัง API

ปัญหาที่รู้จัก

ตรวจสอบหน้าปัญหาสำหรับรายการปัญหาที่ทราบและสำหรับการปรับปรุงที่วางแผนไว้ของห้องสมุด

อย่าลังเลที่จะเปิดปัญหาใหม่หากคุณพบข้อผิดพลาดหรือหากคุณมีคำถาม / คำขอคุณสมบัติ!

ซื้อเบียร์ให้ฉัน

หากคุณพบว่างานของฉันมีประโยชน์และกำลังพิจารณาการบริจาคเล็กน้อยส่วนเกี่ยวกับแอพโชว์เคสมีตัวเลือกให้คุณทำเช่นนั้น ขอบคุณล่วงหน้า!

ใบอนุญาต

 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.