magpie_log – A Flutter‑Based Cross‑Platform Visual Event Tracking Solution

magpie_log is an open‑source project that offers a one‑stop solution for visual event tracking (埋点) in Flutter applications, aiming to eliminate the coupling of manual instrumentation with business logic and to address performance issues caused by frequent interactions in hybrid development.

The project background highlights the pain points of native event tracking, such as strong coupling with UI and lack of parameter support, and notes that existing native automatic tracking solutions either lack parameter passing or consume excessive resources.

After evaluating two main automatic tracking approaches—visual tracking based on dynamic proxies and full tracking based on ASM—the authors chose a visual‑tracking‑oriented design, optimized for Flutter’s characteristics.

Architecture : The solution intercepts events via three mechanisms—Redux action interception, Navigator navigation interception, and setState interception—while also providing manual tracking APIs for coverage gaps. It supports parameter cascading through the MVVM pattern, allowing ViewModels to supply additional data.

Implementation details include:

Action interception using Redux middleware to capture and log actions.

Parameter cascading by accessing global store data in the ViewModel.

Visual configuration implemented on the native side to keep the UI lightweight.

Navigator‑based page exposure tracking via a LogObserver that maintains a custom page stack.

SetState interception through a WidgetLogState subclass (not recommended due to high coupling).

Manual tracking API, e.g., MagpieStatisticsHandler.instance.writeData({'data': '手动埋点数据示例'}); .

The configuration system consists of four parts: tracking definitions, configuration files (managed across assets, disk, and memory), basic UI settings, and reporting settings. Reporting supports per‑event, timed, and count‑based strategies, with separate channels for Android and iOS to minimize cross‑language overhead.

The overall workflow involves initializing configuration files from assets, intercepting actions in debug mode to trigger visual selection and generate configuration files, and directly reporting in release mode. Diagrams in the original article illustrate the basic flow, detailed work process, and future roadmap.

Future plans aim for a more dynamic, server‑driven configuration system, broader coverage beyond Redux, and enhanced parameter cascading capabilities.

In conclusion, magpie_log provides a comprehensive, open‑source tracking solution suitable for pure Flutter and hybrid projects, with the source code available at https://github.com/wuba/magpie_log .