beagle
2.9.8
Une bibliothèque de menu de débogage intelligente, fiable et hautement personnalisable pour les applications Android qui prend en charge l'enregistrement d'écran, la journalisation des activités réseau, la génération de rapports de bogues et de nombreuses autres fonctionnalités utiles.
Clone ce référentiel, choisissez une variante de construction et exécutez la configuration de l'application . Cela devrait ressembler à ceci:
Cette application de démonstration contient également des instructions sur la façon de configurer Beagle et comment implémenter les différentes fonctionnalités présentées. Vous devriez certainement envisager de l'essayer si vous souhaitez utiliser la bibliothèque dans vos projets. Si vous n'avez pas envie de le construire par vous-même, vous pouvez également le télécharger depuis le Play Store:
Les tutoriels de l'application couvrent tout à partir de cette lecture, mais plus en détail. Une autre façon d'obtenir une idée de ce qui peut être réalisé avec la bibliothèque est cet article, qui présente divers problèmes qui peuvent être résolus avec Beagle.
Si le mur du texte ci-dessous est trop long pour votre goût, consultez cet GIST qui contient tout le code dont vous avez besoin pour une belle configuration. Sinon, faisons-le pas à pas:
Assurez-vous que ce qui suit fait partie de votre niveau de construction.
allprojects {
repositories {
…
mavenCentral()
}
}L'interface utilisateur réelle du menu de débogage peut être affichée de plusieurs manières, qui est spécifiée par le suffixe de la dépendance. Les versions suivantes existent:
DebugMenuView est votre responsabilité (non recommandée: Shake to Open, Beagle.show() , Beagle.hide() , le VisibilityListener connexe ainsi que la logique de manutention de l'encadre ne fonctionnera pas dans la boîte).Ainsi, par exemple, si vous préférez l'interface utilisateur du tiroir, quelque chose comme ce qui suit doit être ajouté au fichier build.grade de niveau d'application (vérifiez le widget sous l'extrait de code pour la dernière version):
dependencies {
…
def beagleVersion = " 2.9.8 "
debugImplementation " io.github.pandulapeter.beagle:ui-drawer: $b eagleVersion "
releaseImplementation " io.github.pandulapeter.beagle:noop: $b eagleVersion "
}La dernière version est:
Remarque : Dans le cas de l'interface utilisateur du tiroir, si vous avez remplacé la méthode onBackPressed() de Activity , vous remarquerez peut-être que la manipulation de navigation de retour par défaut ne fonctionne pas toujours comme prévu. Pour résoudre ce problème, dans onBackPressed() de chaque Activity , vous devez vérifier que Beagle.hide() renvoie false avant de faire d'autres chèques ou d'appeler la super implémentation.
Juste une ligne de code, de préférence dans la méthode onCreate() de l' Application :
Beagle .initialize( this )Éventuellement, vous pouvez ajouter les paramètres suivants à cette fonction:
themeResourceId , dans le cas où celui utilisé par l' Application / Activity ne convient pas. Remarque: il est recommandé d'étendre un thème .NoActionBar .Par défaut, vous pouvez récupérer Beagle en secouant l'appareil.
Après cela, un certain nombre de modules doivent être fournis, mais cette configuration peut être modifiée à tout moment (à partir de n'importe quel thread) et l'interface utilisateur sera automatiquement mise à jour. La façon la plus simple de le faire est d'appeler:
Beagle .set(module1, module2, …)À ce stade, vous devez être conscient de deux options:
Consultez l'application Showcase pour quelques idées sur ce qui est possible avec les modules intégrés ou pour un outil interactif qui peut être utilisé pour prévisualiser n'importe quelle configuration du module et générer le code pour cela. Un guide plus visuel de certaines des possibilités est cet article.
Voici un exemple minimal qui devrait fonctionner pour la plupart des projets:
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 ()
) Si vous avez besoin d'ajouter des modules temporaires, Beagle.add() a un paramètre de lifecycleOwner en option qui supprime automatiquement les modules spécifiés une fois le cycle de vie fourni. Appeler manuellement Beagle.remove() avec le module ID-S est également une option.
Bien que l'appel Beagle.log() soit le moyen le plus simple d'ajouter des éléments à LogListModule, une solution de contournement spéciale est nécessaire pour accéder à cette fonctionnalité à partir de modules Kotlin purs. Un autre cas d'utilisation fréquent est l'intégration avec le bois.
Pour accéder aux mêmes fonctionnalités que Beagle.log() fournit à partir d'un module Kotlin / Java pur, vous devez d'abord ajouter ce qui suit au module en question:
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"
} Ces bibliothèques fournissent l'objet BeagleLogger qui doit être connecté à la bibliothèque principale lorsqu'elle est initialisée dans la classe Application :
Beagle .initialize(
…
behavior = Behavior (
…
logBehavior = Behavior . LogBehavior (
loggers = listOf ( BeagleLogger ),
…
)
)
)Pour ajouter des messages de journal, vous pouvez maintenant appeler ce qui suit:
BeagleLogger .log(…) La liste des messages sera fusionnée avec celles enregistrées à l'aide de la fonction Beagle.log() régulière (à moins qu'elles ne soient filtrées par leurs balises) et peuvent être affichées à l'aide d'un logodule LogList. Vous pouvez également utiliser BeagleLogger.clearLogEntries() si vous ne pouvez pas accéder à Beagle.clearLogEntries() .
Pour ajouter automatiquement des événements enregistrés avec du bois au menu de débogage, la plantation d'un arbre spécial est la solution la plus simple:
Timber .plant(
object : Timber . Tree () {
override fun log ( priority : Int , tag : String? , message : String , t : Throwable ? ) =
Beagle .log( " [ $tag ] $message " , " Timber " , t?.stackTraceToString())
}
)Pour créer une loglistModule spéciale qui affiche uniquement ces journaux, définissez simplement le paramètre du constructeur d'étiquette du module sur "Timber".
Ne pas regrouper l'intercepteur réseau avec la bibliothèque principale a été principalement effectué pour fournir une pure dépendance de Kotlin qui n'utilise pas le SDK Android, de la même manière que la solution d'enregistrement décrite ci-dessus. À l'heure actuelle, Beagle ne peut se connecter que dans la bibliothèque de réseautage OKHTTP pour fournir du contenu pour NetworkLogListModule, mais appeler manuellement Beagle.logNetworkEvent() est toujours une option.
Ajoutez ce qui suit au module où votre logique de réseautage est implémentée:
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"
} Cela introduira l'objet BeagleOkHttpLogger qui doit d'abord être connecté à la bibliothèque principale, le moment où il est initialisé:
Beagle .initialize(
…
behavior = Behavior (
…
networkLogBehavior = Behavior . NetworkLogBehavior (
networkLoggers = listOf ( BeagleOkHttpLogger ),
…
)
)
) La dernière étape consiste à mettre en place l' Interceptor (le casting maladroit est là pour s'assurer que l'implémentation de NOOP ne fait rien tout en ayant la même API publique):
val client = OkHttpClient . Builder ()
…
. apply { ( BeagleOkHttpLogger .logger as ? Interceptor ? )?. let { addInterceptor(it) } }
.build()La bibliothèque peut intercepter les exceptions non revues et afficher leur trace de pile dans une boîte de dialogue. Les utilisateurs pourront partager le rapport Crash à l'aide de l'écran de rapport de bogue qui s'ouvre automatiquement. Cette fonctionnalité est obtenue grâce à une dépendance distincte qui doit être ajoutée au module principal (où Beagle est initialisé):
dependencies {
…
debugImplementation " io.github.pandulapeter.beagle:log-crash: $b eagleVersion "
releaseImplementation " io.github.pandulapeter.beagle:log-crash-noop: $b eagleVersion "
} Une fois les dépendances ajoutées, l'objet BeagleCrashLogger nouvellement introduit doit être connecté à la bibliothèque principale:
Beagle .initialize(
…
behavior = Behavior (
…
bugReportingBehavior = Behavior . BugReportingBehavior (
crashLoggers = listOf ( BeagleCrashLogger ),
…
)
)
)L'utilisation de cette fonctionnalité simultanément avec d'autres solutions de rapport de crash peut être peu fiable.
Veuillez également noter qu'en introduisant la dépendance log-crash , l'activité de rapport de bogue de Beagle s'exécutera désormais dans un processus distinct (Firebase par exemple a besoin d'un appel d'initialisation spécial pour les applications multi-processus).
Les implémentations noop de chaque artefact public sont les moyens par défaut de ne pas inclure la logique liée au Beagle dans vos versions de production. Bien que cela devrait être assez bon pour la plupart des projets, il peut être amélioré en créant un module de wrapper distinct pour le menu de débogage. Cela signifierait cacher chaque appel à Beagle derrière une interface qui a une implémentation vide dans les versions de version. Cette approche a ses propres avantages et inconvénients:
noop dans votre configuration actuelleinitialize() dans votre classe Application personnalisée, et cette classe est correctement enregistrée dans le manifesteFragmentActivity (par exemple, AppCompatActivity est un bon choix). Attention, si vous utilisez le modèle Empty Compose Activity d'Android Studio, vous devez modifier la classe parent par défaut! Par défaut, Beagle utilise le thème de Activity actuelle. Cependant, cela nécessite un thème matériel pour fonctionner, donc si vous avez un crash causé par divers attributs de thème qui ne sont pas trouvés, remplacez le thème du menu de débogage avec la propriété themeResourceId de l'instance d'apparence fournie lors de l'initialisation avec un thème matériel.
Beagle fonctionne en ajoutant un Fragment au-dessus de la disposition de chaque Activity . Parfois, ce n'est pas nécessaire ou pas possible. Bien que la bibliothèque soit livrée avec une liste des noms de packages Activity exclus, vous pouvez fournir un filtrage supplémentaire si nécessaire, en utilisant la propriété Lambda de shouldAddDebugMenu de l'instance de comportement fournie lors de l'initialisation.
Définissez un themeResourceId de .NoActionBar .
Toutes les fonctions publiques sont documentées avec KDOC. Le fichier BeagleContract est un bon début pour en savoir plus sur toutes les capacités intégrées. Pour plus d'informations sur les modules individuels, consultez les en-têtes de classe pertinents.
Si vous êtes intéressé par ce qui se trouve sous le capot, ce document peut être utile lors de la navigation dans le code source.
Consultez la page des versions pour les modifications de chaque version.
La bibliothèque utilise le versioning sémantique: major.minor.patch où les modifications du correctif ne contiennent que des corrections de bugs, les modifications mineures ajoutent de nouvelles fonctionnalités et les modifications majeures introduisent des modifications de rupture à l'API.
Consultez la page des problèmes pour la liste des problèmes connus et pour les améliorations prévues de la bibliothèque.
N'hésitez pas à ouvrir un nouveau problème si vous trouvez un bogue ou si vous avez des questions / demandes de fonctionnalités!
Si vous avez trouvé mon travail utile et envisagez un petit don, la section à propos de l'application Showcase a une option pour vous de le faire. Merci d'avance!
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.
