# Analytics your agent ships with ads denied

A container loaded from Google's host, a team plan stored on the user or an email sent as the user id is found only after release. The magic_analytics skill teaches your agent the provider order, the identity rules and the consent wiring before it writes a line, and the MCP server lets it look a signature up in the live docs.

## Ask for the feature, not the API.

Three things people ask for when a Magic app gets analytics. The skill turns each one into the calls and the config magic_analytics expects.

### send an event when a monitor is created, tagged with the team plan

Calls `Analytics.identify` with the user's UUID, puts the plan in `setDefaultParams` so it rides on every event, then sends `monitor_created` with `Analytics.track`.

Reaches for: `Analytics.identify`, `Analytics.setDefaultParams`, `Analytics.track`

### load GA4 on web from our own domain, not from Google

Sets `GTM_CONTAINER_ID` and `GTM_GATEWAY_PATH`, proxies that path to `GTM-XXXXXXX.fps.goog` and keeps `send_page_view` off in the container, because the driver pushes each page view itself.

Reaches for: `GtmWebDriver`, `analyticsConfig`, `Env.filled`

### let users opt out of analytics and remember the choice

Persists the choice in the app and calls `Analytics.setOptOut` during boot, before the first page view, because the package holds the opt-out in memory only.

Reaches for: `Analytics.setOptOut`, `Analytics.isOptedOut`, `Analytics.reset`

## Where agents slip, and what the skill writes instead.

Each of these passes a quick run and shows up later as wrong GA4 data or a lost user. The skill writes the second version.

### A team plan stored as a user property

`setUserProperties` is user-level, so a team switch leaves the old team on the user. The skill puts team facts in `setDefaultParams`, which replaces the set and rides on every event.

without the skill:

```dart
// The old team stays on the user after a switch.
await Analytics.setUserProperties({'team_plan': teamPlan});
```

with the skill:

```dart
// Replaced per team and sent with every event.
await Analytics.setDefaultParams({'team_plan': teamPlan});
```

### An email as the GA4 user id

`identify` refuses an id the scrubber would change, so an email never becomes the user id and the user stays anonymous. The skill passes the user's UUID.

without the skill:

```dart
Future<void> onSignedIn(String email) async {
  // Refused: the scrubber masks an email.
  await Analytics.identify(email);
}
```

with the skill:

```dart
Future<void> onSignedIn(String userUuid) async {
  await Analytics.identify(userUuid);
}
```

### Adding the page view observer by hand

`MagicRouter` refuses an observer once it has built its `routerConfig`. The skill registers `AnalyticsServiceProvider` in `providers`, after error reporting, and its `boot()` adds the observer in time.

without the skill:

```dart
// Too late once the router has built its config.
MagicRouter.instance.addObserver(AnalyticsNavigatorObserver());
```

with the skill:

```dart
final List<Object> providers = [
  // ...your other providers, error reporting first
  (app) => AnalyticsServiceProvider(app),
];
```

## Three pieces, one outcome.

The skill shapes what your agent writes, the MCP server checks it and llms.txt fills the gaps.

### Skill (edit time)

Teaches your agent the provider order, the identity and default parameter rules and the consent wiring before it writes the first line.

### MCP server (runtime)

Lets your agent look an API up in the live docs while it edits, so it never guesses a signature.

### llms.txt (on demand)

A plain-text map of every docs page, for agents that read it once and keep it in context.

## Three paths. Pick one for your editor.

Each path covers this skill; the plugin and the installer cover the whole registry.

### Claude Code plugin

Adds the registry as a marketplace, then installs its plugin.

```bash
/plugin marketplace add anilcancakir/ai
/plugin install anilcancakir@anilcancakir-marketplace
```

### npx skills (recommended)

The universal CLI. It works with the editors the skills package supports.

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

### Universal installer

Detects every supported editor and sets each one up the way it supports: skills, rules, commands or printed steps. It also adds the docs MCP server config.

```bash
git clone https://github.com/anilcancakir/ai.git && cd ai && bash scripts/install.sh --global --with-mcp
```

## Connect the MCP server.

One endpoint at `mcp.anilcancakir.com/magic_analytics`, six clients. Pick yours and paste the config.

(placeholder endpoint)

### What your agent asks the server

- `search_docs "AnalyticsServiceProvider boot observer"`: What the provider wires on boot and why `MagicRouter` refuses an observer once its config is built.
- `search_docs "GtmWebDriver gateway_path"`: How the container loads lazily from the first-party path and what each call pushes to the data layer.
- `search_docs "UrlScrubber scrub"`: Which query keys, route params and email shapes are masked, and which inputs the facade scrubs.

### Claude Code

`terminal`

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

### Cursor

`.cursor/mcp.json`

```json
{
    "mcpServers": {
        "magic_analytics": {
            "type": "http",
            "url": "https://mcp.anilcancakir.com/magic_analytics"
        }
    }
}
```

### OpenCode

`opencode.json`

```json
{
    "mcp": {
        "magic_analytics": {
            "type": "remote",
            "url": "https://mcp.anilcancakir.com/magic_analytics"
        }
    }
}
```

### VS Code Copilot

`.vscode/mcp.json`

```json
{
    "servers": {
        "magic_analytics": {
            "type": "http",
            "url": "https://mcp.anilcancakir.com/magic_analytics"
        }
    }
}
```

### Codex CLI

`~/.codex/config.toml`

```toml
[mcp_servers.magic_analytics]
url = "https://mcp.anilcancakir.com/magic_analytics"
```

### Antigravity CLI

`~/.gemini/config/mcp_config.json`

```json
{
    "mcpServers": {
        "magic_analytics": {
            "serverUrl": "https://mcp.anilcancakir.com/magic_analytics"
        }
    }
}
```

## LLM inventory files

Plain-text maps of the docs for agents that read on demand.

- [llms.txt](https://anilcancakir.com/magic/docs/analytics/llms.txt): An index of every docs page with its Markdown link.
- [llms-full.txt](https://anilcancakir.com/magic/docs/analytics/llms-full.txt): Every docs page in one file.

## Frequently asked

### What does plugin:install set up, and what is still mine to do?

It publishes `lib/config/analytics.dart`, registers `AnalyticsServiceProvider` in `lib/config/app.dart` and adds `analyticsConfig` to the config factories. It writes no native file and cannot set up a web server, so the native keys and the gateway proxy are yours.

### Why does the web driver need a gateway path?

So the container is never requested from `googletagmanager.com`. The web driver needs both `GTM_CONTAINER_ID` and `GTM_GATEWAY_PATH`, a path on your origin proxied to `GTM-XXXXXXX.fps.goog`; without them it is the null driver.

### Does the skill also teach GA4, GTM or Firebase?

No. It covers `magic_analytics` only. The Magic framework is the `magic-framework` skill, and GA4, GTM and Firebase are Google's own documentation; the MCP server looks `magic_analytics` APIs up while the agent edits.

### Why do opted-out web users still show up in GA4?

The container has to honour the consent update: require `analytics_storage` on both the Google tag and the GA4 Event tag, or a denied tag still sends cookieless pings. The opt-out itself lives in memory, so set it again on every start.

### Which AI coding assistants are supported?

The skill installs into Claude Code, Cursor, OpenCode, VS Code Copilot and Codex CLI. Any client that speaks MCP over HTTP or stdio can use the server.

### Where do I report a mistake?

Open an issue on the Magic Analytics repository on GitHub with the prompt, what your agent wrote and the docs page that says otherwise.
