analytics-setup
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAnalytics 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:
-
Which provider(s)?
- TelemetryDeck (privacy-friendly, recommended)
- Firebase Analytics
- Mixpanel
- None (NoOp for now, add later)
-
What events to track?
- App lifecycle (launch, background, foreground)
- Screen views
- User actions (buttons, features used)
- Errors
- Custom events
-
User properties?
- App version
- Subscription status
- Custom properties
通过 AskUserQuestion 询问用户:
-
使用哪些提供商?
- TelemetryDeck(注重隐私,推荐)
- Firebase Analytics
- Mixpanel
- None(暂时采用 NoOp,后续再添加)
-
需要跟踪哪些事件?
- 应用生命周期(启动、进入后台、回到前台)
- 页面查看
- 用户操作(按钮、已使用的功能)
- 错误
- 自定义事件
-
需要哪些用户属性?
- 应用版本
- 订阅状态
- 自定义属性
Generation Process
生成流程
Step 1: Create Core Files
第 1 步:创建核心文件
Always generate these files:
- - Protocol (never changes)
AnalyticsService.swift - - Event definitions (app-specific)
AnalyticsEvent.swift - - For testing/privacy mode
NoOpAnalytics.swift
始终生成以下文件:
- - Protocol(永不改变)
AnalyticsService.swift - - 事件定义(与具体应用相关)
AnalyticsEvent.swift - - 用于测试或隐私模式
NoOpAnalytics.swift
Step 2: Create Selected Provider(s)
第 2 步:创建选定的提供商
Based on user selection:
TelemetryDeckAnalytics.swiftFirebaseAnalytics.swiftMixpanelAnalytics.swift
根据用户选择创建:
TelemetryDeckAnalytics.swiftFirebaseAnalytics.swiftMixpanelAnalytics.swift
Step 3: Create Environment Integration
第 3 步:创建 Environment 集成
For SwiftUI apps:
- - Environment key for dependency injection
AnalyticsServiceKey.swift
对于 SwiftUI 应用:
- - 用于依赖注入的 Environment key
AnalyticsServiceKey.swift
Step 4: Determine File Location
第 4 步:确定文件位置
Check project structure:
- If exists →
Sources/Sources/Analytics/ - If exists →
App/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.plistTelemetryDeck:
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.plistSwapping Providers Later
后续切换提供商
To switch providers:
- Add new provider file (or generate with this skill)
- Change ONE line in App.swift:
swift
// Before
private let analytics: AnalyticsService = TelemetryDeckAnalytics(...)
// After
private let analytics: AnalyticsService = FirebaseAnalytics()切换提供商的方法:
- 添加新的提供商文件(或使用此 skill 生成)
- 在 App.swift 中更改一行:
swift
// Before
private let analytics: AnalyticsService = TelemetryDeckAnalytics(...)
// After
private let analytics: AnalyticsService = FirebaseAnalytics()Testing
测试
- Use in tests and previews
NoOpAnalytics() - 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/ - 所有模板文件