# Ajanınızın reklamlar kapalı kurduğu analytics

Google'ın sunucusundan yüklenen bir container, kullanıcıya yazılan bir takım planı ya da kullanıcı kimliği olarak giden bir e-posta ancak yayından sonra fark edilir. magic_analytics skill'i ajanınıza, tek satır yazmadan önce provider sırasını, kimlik kurallarını ve onay kurulumunu öğretir; MCP sunucusu da ona imzaları canlı dokümanda aratır.

## API'yi değil, özelliği isteyin.

Bir Magic uygulamasına analytics eklenince en çok istenen üç şey. Skill her birini magic_analytics'in beklediği çağrılara ve config'e çevirir.

### monitör oluşturulunca takım planıyla etiketli bir olay gönder

`Analytics.identify`'ı kullanıcının UUID'siyle çağırır, planı her olayla gitsin diye `setDefaultParams`'a koyar, sonra `monitor_created`'ı `Analytics.track` ile gönderir.

Başvurduğu: `Analytics.identify`, `Analytics.setDefaultParams`, `Analytics.track`

### web'de GA4'ü Google'dan değil kendi alan adımızdan yükle

`GTM_CONTAINER_ID` ve `GTM_GATEWAY_PATH`'i ayarlar, o yolu `GTM-XXXXXXX.fps.goog`'a yönlendirir ve container'da `send_page_view`'i kapalı tutar; çünkü her sayfa görüntülemesini driver kendisi gönderir.

Başvurduğu: `GtmWebDriver`, `analyticsConfig`, `Env.filled`

### kullanıcılar analytics'ten çıkabilsin ve seçim hatırlansın

Seçimi uygulamada saklar ve açılışta, ilk sayfa görüntülemesinden önce `Analytics.setOptOut`'u çağırır; çünkü paket opt-out'u yalnızca bellekte tutar.

Başvurduğu: `Analytics.setOptOut`, `Analytics.isOptedOut`, `Analytics.reset`

## Ajanların takıldığı yerler ve skill'in yerine yazdığı.

Bunların hepsi hızlı bir denemeden geçer, sonra yanlış GA4 verisi ya da kaybolan bir kullanıcı olarak ortaya çıkar. Skill ikinci sürümü yazar.

### Kullanıcı özelliği olarak saklanan takım planı

`setUserProperties` kullanıcı düzeyindedir; takım değişince eski takım kullanıcıda kalır. Skill takım bilgilerini, kümeyi değiştiren ve her olayla giden `setDefaultParams`'a koyar.

skill olmadan:

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

skill ile:

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

### GA4 kullanıcı kimliği olarak e-posta

`identify`, scrubber'ın değiştireceği bir kimliği reddeder; e-posta asla kullanıcı kimliği olmaz ve kullanıcı anonim kalır. Skill kullanıcının UUID'sini verir.

skill olmadan:

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

skill ile:

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

### Sayfa görüntüleme gözlemcisini elle eklemek

`MagicRouter`, `routerConfig`'ini kurduktan sonra gözlemci kabul etmez. Skill `AnalyticsServiceProvider`'ı hata raporlamanın ardından `providers` listesine kaydeder; gözlemciyi zamanında onun `boot()`'u ekler.

skill olmadan:

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

skill ile:

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

## Üç parça, tek sonuç.

Skill ajanınızın yazdığını şekillendirir, MCP sunucusu kontrol eder, llms.txt boşlukları doldurur.

### Skill (düzenleme anı)

Ajanınıza provider sırasını, kimlik ve varsayılan parametre kurallarını ve onay kurulumunu ilk satırı yazmadan önce öğretir.

### MCP sunucusu (çalışma zamanı)

Ajanınızın düzenlerken bir API'yi canlı dokümanda aramasını sağlar; imza uydurmaz.

### llms.txt (istenince)

Her doküman sayfasının düz metin haritası; bir kez okuyup bağlamında tutan ajanlar için.

## Üç yol. Editörünüze uygun olanı seçin.

Her yol bu skill'i kapsar; eklenti ve kurulum betiği tüm kayıt defterini kapsar.

### Claude Code eklentisi

Kayıt defterini marketplace olarak ekler, ardından eklentisini kurar.

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

### npx skills (önerilen)

Evrensel CLI. skills paketinin desteklediği editörlerle çalışır.

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

### Evrensel kurulum

Desteklenen her editörü bulur ve her birini desteklediği biçimde kurar: skill, kural, komut ya da yazdırılan adımlar. Docs MCP sunucusunun ayarını da ekler.

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

## MCP sunucusuna bağlanın.

`mcp.anilcancakir.com/magic_analytics` adresinde tek uç nokta, altı istemci. Birini seçin, yapılandırmayı yapıştırın.

(yer tutucu uç nokta)

### Ajanınızın sunucuya sordukları

- `search_docs "AnalyticsServiceProvider boot observer"`: Provider'ın açılışta neyi bağladığı ve `MagicRouter`'ın config'i kurulduktan sonra neden gözlemci kabul etmediği.
- `search_docs "GtmWebDriver gateway_path"`: Container'ın birinci taraf yoldan nasıl tembel yüklendiği ve her çağrının data layer'a ne gönderdiği.
- `search_docs "UrlScrubber scrub"`: Hangi sorgu anahtarlarının, route parametrelerinin ve e-posta biçimlerinin maskelendiği ve facade'ın hangi girdileri temizlediği.

### 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 envanter dosyaları

Dokümanların, isteğe bağlı okuyan ajanlar için düz metin haritaları.

- [llms.txt](https://anilcancakir.com/magic/docs/analytics/llms.txt): Her doküman sayfasının Markdown bağlantısıyla dizini.
- [llms-full.txt](https://anilcancakir.com/magic/docs/analytics/llms-full.txt): Tüm doküman sayfaları tek dosyada.

## Sık sorulanlar

### plugin:install neyi kurar, bana ne kalır?

`lib/config/analytics.dart` dosyasını yayımlar, `AnalyticsServiceProvider`'ı `lib/config/app.dart` içine kaydeder ve `analyticsConfig`'i config factory'lerine ekler. Native dosya yazmaz ve web sunucusu kuramaz; native anahtarlar ve gateway proxy'si size kalır.

### Web driver'ı neden bir gateway yolu ister?

Container hiçbir zaman `googletagmanager.com`'dan istenmesin diye. Web driver'ı hem `GTM_CONTAINER_ID` hem `GTM_GATEWAY_PATH` ister: origin'inizde `GTM-XXXXXXX.fps.goog`'a yönlendirilen bir yol. İkisi yoksa null driver'dır.

### Skill GA4, GTM ya da Firebase'i de öğretir mi?

Hayır. Yalnızca `magic_analytics`'i kapsar. Magic framework'ü `magic-framework` skill'idir; GA4, GTM ve Firebase ise Google'ın kendi dokümanıdır. MCP sunucusu ajan düzenlerken `magic_analytics` API'lerini arar.

### Opt-out yapan web kullanıcıları GA4'te neden hâlâ görünüyor?

Container onay güncellemesine uymalı: hem Google tag'de hem GA4 Event tag'de `analytics_storage`'ı zorunlu kılın, yoksa reddedilmiş bir tag cookie'siz ping göndermeye devam eder. Opt-out da bellekte durur; her açılışta yeniden ayarlayın.

### Hangi yapay zeka kodlama asistanları destekleniyor?

Skill; Claude Code, Cursor, OpenCode, VS Code Copilot ve Codex CLI içine kurulur. HTTP ya da stdio üzerinden MCP konuşan her istemci sunucuyu kullanabilir.

### Bir hatayı nereye bildiririm?

GitHub'daki Magic Analytics deposunda; istemi, ajanınızın yazdığını ve aksini söyleyen doküman sayfasını ekleyerek bir issue açın.
