/analytics-setup

name: analytics-setup
description: Generates protocol-based analytics infrastructure with swappable providers (TelemetryDeck, Firebase, Mixpanel). Use when user wants to add analytics, track events, or set up telemetry.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-11-08
review_by: 2027-06-22

Analytics Setup Generator

Generate a protocol-based analytics infrastructure that makes it easy to swap providers without changing app code.

When This Skill Activates

Use this skill when the user:

• Asks to "add analytics" or "set up analytics"
• Mentions "TelemetryDeck", "Firebase Analytics", "Mixpanel"
• Wants to "track events" or "add telemetry"
• Asks about "privacy-friendly analytics"
• Wants to swap analytics providers

Key Feature: Swappable Providers

The generated code uses a protocol-based architecture:

// Your app uses the protocol
analytics.track(.buttonTapped("subscribe"))

// Swap providers by changing ONE line:
let analytics: AnalyticsService = TelemetryDeckAnalytics() // or FirebaseAnalytics()

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing analytics implementations
• [ ] Look for TelemetryDeck/Firebase/Mixpanel in Package.swift or Podfile
• [ ] Identify source file locations

2. Conflict Detection

Search for existing analytics:

Glob: **/*Analytics*.swift, **/*Telemetry*.swift
Grep: "protocol.*Analytics" or "TelemetryDeck" or "Firebase"

If found, ask user:

• Extend existing analytics?
• Replace with new implementation?
• Add new provider to existing setup?

Configuration Questions

Ask user via AskUserQuestion:

1. **Which provider(s)?**

• TelemetryDeck (privacy-friendly, recommended)
• Firebase Analytics
• Mixpanel
• None (NoOp for now, add later)

2. **What events to track?**

• App lifecycle (launch, background, foreground)
• Screen views
• User actions (buttons, features used)
• Errors
• Custom events

3. **User properties?**

• App version
• Subscription status
• Custom properties

Generation Process

Step 1: Create Core Files

Always generate these files: 1. `AnalyticsService.swift` - Protocol (never changes) 2. `AnalyticsEvent.swift` - Event definitions (app-specific) 3. `NoOpAnalytics.swift` - For testing/privacy mode

Step 2: Create Selected Provider(s)

Based on user selection:

• `TelemetryDeckAnalytics.swift`
• `FirebaseAnalytics.swift`
• `MixpanelAnalytics.swift`

Step 3: Create Environment Integration

For SwiftUI apps:

• `AnalyticsServiceKey.swift` - Environment key for dependency injection

Step 4: Determine File Location

Check project structure:

• If `Sources/` exists → `Sources/Analytics/`
• If `App/` exists → `App/Analytics/`
• Otherwise → `Analytics/`

Output Format

After generation, provide:

Files Created

Sources/Analytics/
├── AnalyticsService.swift          # Protocol (stable interface)
├── AnalyticsEvent.swift            # Your app's events
├── Providers/
│   ├── NoOpAnalytics.swift         # Testing/privacy
│   └── [Provider]Analytics.swift   # Selected provider(s)
└── AnalyticsServiceKey.swift       # SwiftUI Environment (optional)

Integration Steps

**App Entry Point:**

@main
struct MyApp: App {
    // Choose your provider. Always wrap it: Guideline 5.1.1(ii) requires consent
    // even for anonymous usage data, in every region.
    private let analytics: AnalyticsService = ConsentAwareAnalytics(
        wrapped: TelemetryDeckAnalytics(appID: "YOUR-APP-ID"),
        consentProvider: { UserDefaults.standard.bool(forKey: "analyticsConsent") }
    )

    init() {
        analytics.configure()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.analytics, analytics)
        }
    }
}

**Tracking Events:**

struct ContentView: View {
    @Environment(\.analytics) private var analytics

    var body: some View {
        Button("Subscribe") {
            analytics.track(.buttonTapped("subscribe"))
        }
    }
}

Required Dependencies

**TelemetryDeck:**

// Package.swift
.package(url: "https://github.com/TelemetryDeck/SwiftClient", from: "1.0.0")

**Firebase:**

// Package.swift
.package(url: "https://github.com/firebase/firebase-ios-sdk", from: "10.0.0")
// Also requires GoogleService-Info.plist

Swapping Providers Later

To switch providers: 1. Add new provider file (or generate with this skill) 2. Change ONE line in App.swift:

// Before
private let analytics: AnalyticsService = TelemetryDeckAnalytics(...)

// After
private let analytics: AnalyticsService = FirebaseAnalytics()

Testing

• Use `NoOpAnalytics()` in tests and previews
• All tracking calls become no-ops
• No external dependencies in tests

References

• **analytics-patterns.md** - Protocol architecture and best practices
• **templates/** - All template files