analytics-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analytics Setup Generator

分析设置生成器

Generate a protocol-based analytics infrastructure that makes it easy to swap providers without changing app code.
生成基于 Protocol 的分析基础设施,使开发者无需更改应用代码即可轻松切换提供商。

When This Skill Activates

Skill 激活条件

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
当用户出现以下情况时使用此 skill:
  • 要求“添加分析”或“设置分析”
  • 提到“TelemetryDeck”、“Firebase Analytics”或“Mixpanel”
  • 希望“跟踪事件”或“添加遥测”
  • 询问“注重隐私的分析方案”
  • 希望切换数据分析提供商

Key Feature: Swappable Providers

核心功能:可替换的提供商

The generated code uses a protocol-based architecture:
swift
// Your app uses the protocol
analytics.track(.buttonTapped("subscribe"))

// Swap providers by changing ONE line:
let analytics: AnalyticsService = TelemetryDeckAnalytics() // or FirebaseAnalytics()
生成的代码采用基于 Protocol 的架构:
swift
// 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

1. 项目上下文检测

  • Check for existing analytics implementations
  • Look for TelemetryDeck/Firebase/Mixpanel in Package.swift or Podfile
  • Identify source file locations
  • 检查是否已有分析实现
  • 在 Package.swift 或 Podfile 中查找 TelemetryDeck、Firebase、Mixpanel
  • 确定源文件位置

2. Conflict Detection

2. 冲突检测

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?
搜索已有的分析实现:
Glob: **/*Analytics*.swift, **/*Telemetry*.swift
Grep: "protocol.*Analytics" or "TelemetryDeck" or "Firebase"
如果找到现有实现,询问用户:
  • 扩展现有分析实现?
  • 替换为新实现?
  • 在现有配置中添加新的提供商?

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
通过 AskUserQuestion 询问用户:
  1. 使用哪些提供商?
    • TelemetryDeck(注重隐私,推荐)
    • Firebase Analytics
    • Mixpanel
    • None(暂时采用 NoOp,后续再添加)
  2. 需要跟踪哪些事件?
    • 应用生命周期(启动、进入后台、回到前台)
    • 页面查看
    • 用户操作(按钮、已使用的功能)
    • 错误
    • 自定义事件
  3. 需要哪些用户属性?
    • 应用版本
    • 订阅状态
    • 自定义属性

Generation Process

生成流程

Step 1: Create Core Files

第 1 步:创建核心文件

Always generate these files:
  1. AnalyticsService.swift
    - Protocol (never changes)
  2. AnalyticsEvent.swift
    - Event definitions (app-specific)
  3. NoOpAnalytics.swift
    - For testing/privacy mode
始终生成以下文件:
  1. AnalyticsService.swift
    - Protocol(永不改变)
  2. AnalyticsEvent.swift
    - 事件定义(与具体应用相关)
  3. NoOpAnalytics.swift
    - 用于测试或隐私模式

Step 2: Create Selected Provider(s)

第 2 步:创建选定的提供商

Based on user selection:
  • TelemetryDeckAnalytics.swift
  • FirebaseAnalytics.swift
  • MixpanelAnalytics.swift
根据用户选择创建:
  • TelemetryDeckAnalytics.swift
  • FirebaseAnalytics.swift
  • MixpanelAnalytics.swift

Step 3: Create Environment Integration

第 3 步:创建 Environment 集成

For SwiftUI apps:
  • AnalyticsServiceKey.swift
    - Environment key for dependency injection
对于 SwiftUI 应用:
  • AnalyticsServiceKey.swift
    - 用于依赖注入的 Environment key

Step 4: Determine File Location

第 4 步:确定文件位置

Check project structure:
  • If
    Sources/
    exists →
    Sources/Analytics/
  • If
    App/
    exists →
    App/Analytics/
  • Otherwise →
    Analytics/
检查项目结构:
  • 如果存在
    Sources/
    →
    Sources/Analytics/
  • 如果存在
    App/
    →
    App/Analytics/
  • 否则 →
    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)
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:
swift
@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:
swift
struct ContentView: View {
    @Environment(\.analytics) private var analytics

    var body: some View {
        Button("Subscribe") {
            analytics.track(.buttonTapped("subscribe"))
        }
    }
}
应用入口:
swift
@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)
        }
    }
}
跟踪事件:
swift
struct ContentView: View {
    @Environment(\.analytics) private var analytics

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

Required Dependencies

所需依赖项

TelemetryDeck:
swift
// Package.swift
.package(url: "https://github.com/TelemetryDeck/SwiftClient", from: "1.0.0")
Firebase:
swift
// Package.swift
.package(url: "https://github.com/firebase/firebase-ios-sdk", from: "10.0.0")
// Also requires GoogleService-Info.plist
TelemetryDeck:
swift
// Package.swift
.package(url: "https://github.com/TelemetryDeck/SwiftClient", from: "1.0.0")
Firebase:
swift
// 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:
swift
// Before
private let analytics: AnalyticsService = TelemetryDeckAnalytics(...)

// After
private let analytics: AnalyticsService = FirebaseAnalytics()
切换提供商的方法:
  1. 添加新的提供商文件(或使用此 skill 生成)
  2. 在 App.swift 中更改一行:
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
  • 在测试和预览中使用
    NoOpAnalytics()
  • 所有跟踪调用都会成为 no-op
  • 测试中不依赖任何外部组件

References

参考资料

  • analytics-patterns.md - Protocol architecture and best practices
  • templates/ - All template files
  • analytics-patterns.md - Protocol 架构与最佳实践
  • templates/ - 所有模板文件