# Magic Analytics

**GA4 for your Magic app, with ads denied.**

One `Analytics` facade for the Magic framework: Google Tag Manager on web, served from your own domain, and Firebase on iOS and Android. Emails and tokens are scrubbed before anything leaves.

Runs on: Android, iOS, Web

Parent package: [Magic](https://anilcancakir.com/magic/index.md)

## One facade. Every platform.

GA4, Tag Manager and Firebase know nothing about the Magic router, its auth state or your route patterns. Magic Analytics connects them, so a page view carries the pattern and a sign-out clears the user.

### One Analytics facade

`track`, `identify`, `setUserProperties` and `setDefaultParams` run in call order through one facade, and a driver failure is logged, never thrown into UI flow.

- Team facts go in `setDefaultParams`, which replaces the set and rides on every event
- A call that breaks a GA4 limit fails an assert in debug and is dropped in release

```dart
Future<void> afterSignIn(String userUuid, String teamPlan) async {
  await Analytics.identify(userUuid);
  await Analytics.setDefaultParams({'team_plan': teamPlan});
  await Analytics.track('monitor_created', {'monitor_type': 'http'});
}
```

[Read the docs about One Analytics facade](https://anilcancakir.com/magic/docs/analytics/basics/facade-and-provider.md)

### Page views by pattern

An observer on `MagicRouter` reports each named page with its route pattern as the location, so no id, token or email leaves the device.

- Every monitor counts as `/monitors/:id`, never `/monitors/42`
- A dialog or a bottom sheet is no page view, and closing one reports nothing

```dart
Future<void> onTabChanged(String tab) {
  return Analytics.screen('monitor_$tab', location: '/monitors/:id/$tab');
}
```

[Read the docs about Page views by pattern](https://anilcancakir.com/magic/docs/analytics/basics/facade-and-provider.md)

### GTM on web, Firebase on mobile

Web loads a Tag Manager container from a path on your own origin, iOS and Android send through Firebase, and without IDs a null driver sends nothing.

- The container is never requested from `googletagmanager.com`
- Firebase is never initialised on web

[Read the docs about GTM on web, Firebase on mobile](https://anilcancakir.com/magic/docs/analytics/basics/drivers.md)

### Ads always denied

`ad_storage`, `ad_user_data` and `ad_personalization` are denied on every start, and `Analytics.setOptOut` stops everything else on the device.

- No config key or call grants the ad signals
- The opt-out is held in memory: persist it and set it before the first page view

```dart
Future<void> restoreOptOut(bool storedOptOut) {
  return Analytics.setOptOut(storedOptOut);
}
```

[Read the docs about Ads always denied](https://anilcancakir.com/magic/docs/analytics/basics/consent-and-opt-out.md)

### URL scrubbing

`UrlScrubber` masks emails and tokens in every page location, title and string parameter before anything is sent.

- Query values whose key names `token`, `password`, `email` or `code` become `[Filtered]`
- `identify` refuses an id the scrubber would change, so an email is never the user id

[Read the docs about URL scrubbing](https://anilcancakir.com/magic/docs/analytics/guides/url-scrubbing.md)

### Tests without a property

`Analytics.fake()` binds the real manager over a recording driver, so a test sees only what passed validation, scrubbing and the opt-out gate.

- `assertTracked`, `assertNotTracked` and `assertNothingSent` need no mocking library
- Call `Analytics.fake()` after the provider registers, inside a `testWidgets` body

```dart
test('creating a monitor sends one event', () async {
  final FakeAnalytics fake = Analytics.fake();

  await Analytics.track('monitor_created');

  fake.assertTracked('monitor_created');
});
```

[Read the docs about Tests without a property](https://anilcancakir.com/magic/docs/analytics/guides/testing.md)

## Your agent speaks Magic Analytics.

The Magic Analytics skill teaches your coding assistant the provider order, the gateway and the consent rules the framework expects, before the first line. One command wires it up.

```bash
npx skills add anilcancakir/ai --skill magic-analytics
```

[other editors](https://github.com/anilcancakir/ai)

## And checks the docs.

Skills teach the wiring. The MCP server at `mcp.anilcancakir.com/magic_analytics` gives your agent live docs lookup while it edits, so it never guesses a signature.

```bash
claude mcp add --transport http magic_analytics https://mcp.anilcancakir.com/magic_analytics
```

```bash
npx -y mcp-remote https://mcp.anilcancakir.com/magic_analytics
```

## Questions, answered.

What people ask before they add Magic Analytics to a Flutter app.

### What is Magic Analytics?

Magic Analytics is the GA4 plugin for Magic apps. One `Analytics` facade sends through Google Tag Manager on web and Firebase on iOS and Android, reports page views by route pattern and keeps every ad signal denied.

### How do I install Magic Analytics?

Run `flutter pub add magic_analytics`, then `dart run magic:dowel plugin:install magic_analytics`. The installer publishes `lib/config/analytics.dart`, registers `AnalyticsServiceProvider` and adds `analyticsConfig` to the config factories; it writes no native file and cannot set up your web server.

### Which platforms does Magic Analytics support?

Web through Google Tag Manager, and iOS and Android through Firebase. It requires Dart 3.13+, Flutter 3.47+ and `magic` ^1.0.0; Firebase is never initialised on web.

### Does Magic Analytics send anything without IDs?

No. Unless `ANALYTICS_ENABLED` is `true`, `1` or `yes`, the provider binds a null driver that sends nothing, and the web driver also needs both `GTM_CONTAINER_ID` and `GTM_GATEWAY_PATH`.

### Can Magic Analytics turn ad signals on?

No. `ad_storage`, `ad_user_data` and `ad_personalization` are denied on every start, on every platform, and no config key or call grants them. Analytics storage is granted by default; the device opt-out is what stops collection.

### Does Magic Analytics work with AI coding agents?

Yes. Magic Analytics ships an agent skill that teaches your assistant the provider order, the identity and default parameter rules and the consent wiring, plus a public docs MCP server for live lookup.

### Is Magic Analytics open source?

Yes. Magic Analytics is open source under the MIT license.

## Add it in seconds

```bash
flutter pub add magic_analytics
```

Or add to `pubspec.yaml`:

```yaml
dependencies:
  magic_analytics: ^1.0.1
```

Or give your AI agent this prompt:

```text
Read https://anilcancakir.com/magic/docs/analytics/llms.txt and install the Magic Analytics package in this project.
```

## More Magic plugins

- [Starter](https://anilcancakir.com/magic/starter/index.md): Auth, profile, teams and notifications screens, ready to use.
- [Payments](https://anilcancakir.com/magic/payments/index.md): One entitlement contract over web billing and store purchase on iOS and Android.
- [Notifications](https://anilcancakir.com/magic/notifications/index.md): In-app and OneSignal push notifications through one facade.
- [Social Auth](https://anilcancakir.com/magic/social_auth/index.md): Native Google (iOS, Android) and Apple (iOS) sign-in, plus a browser flow for the rest.
- [Socket](https://anilcancakir.com/magic/socket/index.md): Real-time broadcasting: public, private and presence channels over Reverb.
- [Local Storage](https://anilcancakir.com/magic/local_storage/index.md): SQLite with migrations, seeders and factories.
- [Deeplink](https://anilcancakir.com/magic/deeplink/index.md): Universal Links on iOS and App Links on Android through one API.
- [Picker](https://anilcancakir.com/magic/picker/index.md): Pick a file, an image or a video and get a MagicFile back.
- [Encryption](https://anilcancakir.com/magic/encryption/index.md): Values kept opaque at rest on the device with AES-256-CBC.
- [Sentry](https://anilcancakir.com/magic/sentry/index.md): Sentry error and performance monitoring, wired in.
- [Device](https://anilcancakir.com/magic/device/index.md): Know whether the device is on mains power and whether the viewer is away.
- [Devtools](https://anilcancakir.com/magic/devtools/index.md): Magic-aware context for tapir and crumbs, so an agent sees your app the way Magic does.

## Docs

### Getting Started

- [Installation](https://anilcancakir.com/magic/docs/analytics/getting-started/installation.md)

### The Basics

- [Facade and Provider](https://anilcancakir.com/magic/docs/analytics/basics/facade-and-provider.md)
- [Drivers](https://anilcancakir.com/magic/docs/analytics/basics/drivers.md)
- [Consent and Opt-Out](https://anilcancakir.com/magic/docs/analytics/basics/consent-and-opt-out.md)

### Guides

- [Testing](https://anilcancakir.com/magic/docs/analytics/guides/testing.md)
- [URL Scrubbing](https://anilcancakir.com/magic/docs/analytics/guides/url-scrubbing.md)
