magic_analytics 1.0.0
magic_analytics: ^1.0.0 copied to clipboard
Analytics for Magic apps: GA4 through GTM on web, Firebase on iOS and Android, one Analytics facade. Ad signals always denied, inert without IDs.
Changelog #
All notable changes to this project will be documented in this file.
[Unreleased] #
1.0.0 - 2026-11-20 #
Added #
- Package scaffold. Repository files, workflows and the docs gate required by the package standard. (
pubspec.yaml,.github/,tool/check-docs.py) - The
Analyticsfacade andAnalyticsManager.track,screen,identify,setUserProperties,setDefaultParams,setOptOut,resetandclientId, validated against the GA4 limits (anassertin debug, a dropped call with a log in release), scrubbed, gated on the device opt-out and sent to the driver in call order. A driver error is logged and never thrown into UI flow. (lib/src/facades/analytics.dart) - Three drivers behind one contract.
GtmWebDriverloads a Google Tag Manager container lazily from a first-party gateway path and never on an opted-out device;FirebaseDriverserves iOS and Android and Firebase is never initialised on web;NullDriversends nothing, so the package is inert untilANALYTICS_ENABLED(true,1oryes) and the IDs are set. Ad signals are denied on every start; analytics storage is granted unless the device opts out. Beforegtm.jsthe GTM bootstrap pre-seedspage_locationandpage_referrerwith the origin root, and the first page view's referrer is that root, so the Google tag never reads a tokenised address bar. (lib/src/drivers/) AnalyticsServiceProviderandAnalyticsNavigatorObserver. The provider binds the manager, adds the page view observer toMagicRouterand resets analytics when the signed-in user signs out or changes. Page views carry the route name as the title and the route pattern as the location, never the real URL. (lib/src/analytics_service_provider.dart,lib/src/observers/analytics_navigator_observer.dart)UrlScrubber. Masks secret query values, route-bound token segments and email addresses in every string that leaves the device. (lib/src/support/url_scrubber.dart)Analytics.fake()andFakeAnalytics. A recording driver behind the real manager, withassertTracked,assertNotTrackedandassertNothingSent. (lib/src/testing/fake_analytics.dart)install.yamland the config stub.plugin:installpublisheslib/config/analytics.dart, registersAnalyticsServiceProvider, injects theanalyticsConfigfactory and prints the web gateway,flutterfire configureand native key steps. (install.yaml,assets/stubs/install/analytics_config.stub)lib/cli.dartwithMagicAnalyticsDowelProvider, soplugin:install magic_analyticsregisters under dowel. It contributes no commands, stays Flutter-free, anddowel^1.0.0 is a new dependency. (lib/cli.dart,lib/src/cli/analytics_dowel_provider.dart,pubspec.yaml)doc/: six pages in the repository's docs standard (installation, facade and provider, drivers, consent and opt-out, testing and URL scrubbing), checked bytool/check-docs.py. The drivers page lists the GTM container setup: a GA4 Event tag, data layer variables, a shared Event Settings Variable andanalytics_storagerequired on both tags.llms.txt,skills/magic-analyticsandREADME.md: the package for people and for AI coding agents. The skill is installed withnpx skills add anilcancakir/magic_analyticsand stays out of the pub.dev archive.example/: a runnable Magic app with the provider registered and buttons that send an event, identify a user and toggle the opt-out.