beagle
2.9.8
Eine intelligente, zuverlässige und hoch anpassbare Debug -Menübibliothek für Android -Apps, die Bildschirmaufzeichnung, Netzwerkaktivitätenprotokollierung, Generieren von Fehlerberichten und viele andere nützliche Funktionen unterstützt.
Klonen Sie dieses Repository, wählen Sie eine Build -Variante und führen Sie die App -Konfiguration aus. Es sollte ungefähr so aussehen:
Diese Demo -Anwendung enthält auch Anweisungen zum Einrichten von Beagle und zur Implementierung der verschiedenen Funktionen, die vorgestellt werden. Sie sollten es auf jeden Fall versuchen, es auszuprobieren, wenn Sie die Bibliothek in Ihren Projekten verwenden möchten. Wenn Sie keine Lust haben, es selbst zu erstellen, können Sie es auch aus dem Play Store herunterladen:
Die Tutorials in der App umfassen alles von diesem Readme, aber ausführlicher. Eine andere Möglichkeit, eine Vorstellung davon zu bekommen, was mit der Bibliothek erreicht werden kann, ist dieser Artikel, der verschiedene Probleme aufweist, die mit Beagle gelöst werden können.
Wenn die folgende Textwand für Ihren Geschmack zu lang ist, schauen Sie sich diesen GIST an, der den Code enthält, den Sie für eine schöne Konfiguration benötigen. Ansonsten machen wir es Schritt für Schritt:
Stellen Sie sicher, dass das Folgende Teil Ihres Build-Level-Projekts ist. Gradle-Datei:
allprojects {
repositories {
…
mavenCentral()
}
}Die tatsächliche Benutzeroberfläche des Debug -Menüs kann auf verschiedene Arten angezeigt werden, was durch das Suffix der Abhängigkeit angegeben ist. Die folgenden Versionen existieren:
DebugMenuView liegt in Ihrer Verantwortung (nicht empfohlen: Schütteln, Beagle.show() , Beagle.hide() , der zugehörige VisibilityListener sowie die Logik zur Einschreibung des Einschubs wird nicht funktionieren).Wenn Sie beispielsweise die Benutzeroberfläche der Schublade bevorzugen, muss die folgende Fachdatei auf App-Ebene hinzugefügt werden (überprüfen Sie das Widget unter dem Code-Snippet für die neueste Version):
dependencies {
…
def beagleVersion = " 2.9.8 "
debugImplementation " io.github.pandulapeter.beagle:ui-drawer: $b eagleVersion "
releaseImplementation " io.github.pandulapeter.beagle:noop: $b eagleVersion "
}Die neueste Version ist:
HINWEIS : Wenn Sie die Methode der onBackPressed() der Activity überschrieben haben, können Sie feststellen, dass die Behandlungsnavigationsbehandlung nicht immer wie erwartet funktioniert. Um dies zu beheben, sollten Sie in jeder Activity von onBackPressed() überprüfen, ob Beagle.hide() false zurückgibt, bevor Sie andere Schecks durchführen oder die Super -Implementierung anrufen.
Nur eine Codezeile, vorzugsweise in der onCreate() -Methode der Application :
Beagle .initialize( this )Optional können Sie dieser Funktion die folgenden Parameter hinzufügen:
themeResourceId verwenden, falls die von der Application / Activity verwendete Aktivität nicht geeignet ist. HINWEIS: Es wird empfohlen, ein Materialthema von .NoActionBar zu erweitern.Standardmäßig können Sie Beagle abrufen, indem Sie das Gerät schütteln.
Danach sollte eine Reihe von Modulen bereitgestellt werden, aber diese Konfiguration kann jederzeit (aus jedem Thread) geändert werden und die Benutzeroberfläche wird automatisch aktualisiert. Die einfachste Art, dies zu tun, besteht darin, anzurufen:
Beagle .set(module1, module2, …)Zu diesem Zeitpunkt sollten Sie zwei Optionen bewusst sein:
In der Showcase-App finden Sie einige Ideen für das, was mit den integrierten Modulen möglich ist, oder für ein interaktives Tool, mit dem die Modulkonfiguration eine Vorschau von Modulkonfigurationen voran und den Code für ihn generiert werden kann. Ein visuellerer Leitfaden für einige Möglichkeiten ist dieser Artikel.
Hier ist ein minimales Beispiel, das für die meisten Projekte funktionieren sollte:
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 ()
) Wenn Sie jemals temporäre Module hinzufügen müssen, verfügt Beagle.add() über einen optionalen lifecycleOwner -Parameter, der die angegebenen Module automatisch beseitigt, sobald der bereitgestellte Lebenszyklus vorbei ist. Manuell aufrufen Beagle.remove() mit Modul-ID-S ist ebenfalls eine Option.
Während das Aufrufen von Beagle.log() die einfachste Möglichkeit ist, Elemente zu LogListModule hinzuzufügen, ist eine spezielle Problemumgehung erforderlich, um auf diese Funktionalität aus reinen Kotlin -Modulen zuzugreifen. Ein weiterer häufiger Anwendungsfall ist die Integration mit Holz.
Um auf die gleiche Funktionalität zuzugreifen wie Beagle.log() von einem reinen Kotlin / Java -Modul, müssen Sie zunächst das folgende Modul hinzuzufügen:
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"
} Diese Bibliotheken bieten das BeagleLogger -Objekt, das mit der Hauptbibliothek verbunden werden muss, wenn es in der Application initialisiert wird:
Beagle .initialize(
…
behavior = Behavior (
…
logBehavior = Behavior . LogBehavior (
loggers = listOf ( BeagleLogger ),
…
)
)
)Um Protokollnachrichten hinzuzufügen, können Sie jetzt Folgendes anrufen:
BeagleLogger .log(…) Die Meldungsliste wird mit den angemeldeten mit der regulären Beagle.log() -Funktion (es sei denn, sie werden von ihren Tags filtriert) zusammengeführt und können mit einem LoglistModule angezeigt werden. Sie können auch BeagleLogger.clearLogEntries() verwenden, wenn Sie nicht auf Beagle.clearLogEntries() zugreifen können.
Um automatisch Ereignisse hinzuzufügen, die mit Holz zum Debug -Menü protokolliert sind, ist das Pflanzen eines speziellen Baumes die einfachste Lösung:
Timber .plant(
object : Timber . Tree () {
override fun log ( priority : Int , tag : String? , message : String , t : Throwable ? ) =
Beagle .log( " [ $tag ] $message " , " Timber " , t?.stackTraceToString())
}
)So erstellen Sie ein spezielles LogListModule, das nur diese Protokolle anzeigt, einfach den Label -Konstruktorparameter des Moduls auf "Holz" festlegen.
Das Bündelende des Netzwerk -Interceptors mit der Hauptbibliothek wurde hauptsächlich durchgeführt, um eine reine Kotlin -Abhängigkeit bereitzustellen, die das Android -SDK nicht verwendet, ähnlich wie die oben beschriebene Logger -Lösung. Derzeit kann Beagle nur in die OKHTTP -Netzwerkbibliothek einbinden, um Inhalte für Beagle.logNetworkEvent() bereitzustellen, aber manuell aufzurufen.
Fügen Sie dem Modul Folgendes hinzu, in dem Ihre Netzwerklogik implementiert ist:
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"
} Dadurch wird das BeagleOkHttpLogger -Objekt vorgestellt, das zunächst mit der Hauptbibliothek verbunden werden muss, sobald es initialisiert wird:
Beagle .initialize(
…
behavior = Behavior (
…
networkLogBehavior = Behavior . NetworkLogBehavior (
networkLoggers = listOf ( BeagleOkHttpLogger ),
…
)
)
) Der letzte Schritt ist der Einrichten des Interceptor (das unangenehme Casting ist vorhanden, um sicherzustellen, dass die Noop -Implementierung nichts unternimmt, während sie immer noch dieselbe öffentliche API hat):
val client = OkHttpClient . Builder ()
…
. apply { ( BeagleOkHttpLogger .logger as ? Interceptor ? )?. let { addInterceptor(it) } }
.build()Die Bibliothek kann unbekannte Ausnahmen abfangen und ihre Stapelspur in einem Dialog anzeigen. Benutzer können den Absturzbericht über den Bildschirm "Fehlerberichterstattung" freigeben, der automatisch geöffnet wird. Diese Funktionalität wird durch eine separate Abhängigkeit erreicht, die dem Hauptmodul hinzugefügt werden sollte (wo Beagle initialisiert wird):
dependencies {
…
debugImplementation " io.github.pandulapeter.beagle:log-crash: $b eagleVersion "
releaseImplementation " io.github.pandulapeter.beagle:log-crash-noop: $b eagleVersion "
} Nachdem die Abhängigkeiten hinzugefügt wurden, sollte das neu eingeführte BeagleCrashLogger -Objekt mit der Hauptbibliothek verbunden werden:
Beagle .initialize(
…
behavior = Behavior (
…
bugReportingBehavior = Behavior . BugReportingBehavior (
crashLoggers = listOf ( BeagleCrashLogger ),
…
)
)
)Die gleichzeitige Verwendung dieser Funktion mit anderen Crash -Reporting -Lösungen kann unzuverlässig sein.
Bitte beachten Sie außerdem, dass Beagle's Bugs Reporting-Aktivität durch Einführung der Abhängigkeit log-crash jetzt in einem separaten Prozess ausgeführt wird (Firebase erfordert beispielsweise einen speziellen Initialisierungsaufruf für Multi-Process-Apps).
Die noop Implementierungen jedes öffentlichen Artefakts sind die Standardmethoden, um keine Beagle-bezogene Logik in Ihre Produktionsveröffentlichungen aufzunehmen. Dies sollte zwar für die meisten Projekte gut genug sein, aber es kann verbessert werden, indem ein separates Wrapper -Modul für das Debug -Menü erstellt wird. Dies würde bedeuten, dass jeder Aufruf an Beagle hinter einer Schnittstelle versteckt wird, die eine leere Implementierung in Release -Builds aufweist. Dieser Ansatz hat seine eigenen Vorteile und Nachteile:
noop -Artefakt in Ihrer aktuellen Konfiguration nicht verwendeninitialize() in Ihrer benutzerdefinierten Application aufrufen und diese Klasse im Manifest ordnungsgemäß registriert istFragmentActivity erweitert (z. B. AppCompatActivity ist eine gute Wahl). Achten Sie darauf, dass Sie die Standard Empty Compose Activity ändern müssen! Standardmäßig verwendet Beagle das Thema der aktuellen Activity . Es ist jedoch erforderlich, dass ein materielles Thema funktioniert. Wenn Sie also einen Absturz haben, der durch verschiedene Themenattribute verursacht wird, die nicht gefunden werden, überschreiben Sie das Thema des Debug -Menüs mit der themeResourceId -Eigenschaft der Aussehensinstanz, die während der Initialisierung mit einem materiellen Thema bereitgestellt wird.
Beagle arbeitet, indem er ein Fragment über das Layout jeder Activity hinzufügt. Manchmal ist dies nicht notwendig oder nicht möglich. Während die Bibliothek eine Liste mit ausgeschlossenen Activity enthält, können Sie bei Bedarf zusätzliche Filterung angeben, indem Sie die shouldAddDebugMenu Lambda -Eigenschaft der während der Initialisierung bereitgestellten Verhaltensinstanz verwenden.
Setzen Sie ein .NoActionBar -Material -Thema für die themeResourceId -Eigenschaft der Aussehensinstanz, die während der Initialisierung bereitgestellt wurde.
Alle öffentlichen Funktionen sind mit KDOC dokumentiert. Die Datei BeaGleContract ist ein guter Start, um alle integrierten Funktionen kennenzulernen. Informationen zu den einzelnen Modulen finden Sie in den relevanten Klassenüberschriften.
Wenn Sie an dem, was unter der Haube liegt, interessiert, kann dieses Dokument hilfreich sein, während Sie durch den Quellcode navigieren.
Schauen Sie sich die Releases -Seite für die Änderungen in jeder Version an.
Die Bibliothek verwendet die semantische Versionierung: major.minor.patch, bei dem Patch -Änderungen nur Fehlerbehebungen enthalten, kleinere Änderungen neue Funktionen hinzufügen und wichtige Änderungen in die API brechen.
Schauen Sie sich die Ausgabenseite für die Liste der bekannten Probleme und die geplanten Verbesserungen der Bibliothek an.
Zögern Sie nicht, ein neues Problem zu eröffnen, wenn Sie einen Fehler finden oder Fragen / Feature -Anfragen haben!
Wenn Sie meine Arbeit als nützlich empfanden und eine kleine Spende in Betracht ziehen, verfügt der Abschnitt über die Showcase -App für Sie, um dies zu tun. Dank im Voraus!
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.
