anyproto/analytics-developer

Analytics Developer (Smart Router)

Purpose

Context-aware routing to the Anytype iOS analytics system. Helps you add analytics events, track user routes, and maintain consistent analytics patterns.

When Auto-Activated

• Working with analytics events or AnytypeAnalytics
• Adding route tracking or event properties
• Modifying AnalyticsConstants.swift or AnytypeAnalytics+Events.swift
• Keywords: analytics, route tracking, logEvent, AnytypeAnalytics, AnalyticsConstants

🚨 CRITICAL RULES (NEVER VIOLATE)

1. ALWAYS define route enums in AnalyticsConstants.swift - Never hardcode route strings
2. ALWAYS use existing property keys - Use AnalyticsEventsPropertiesKey.*
3. NEVER use string literals for routes - Use typed enums with .rawValue
4. ALWAYS use .compactMapValues { $0 } for optional properties - Removes nil values
5. ALWAYS track route context - Know how users reached a feature

📋 Quick Workflow

Adding New Analytics Event

1. Define route enum (if needed): Add to AnalyticsConstants.swift
2. Add event method: Add to AnytypeAnalytics+Events.swift
3. Use in code: Call AnytypeAnalytics.instance().logYourEvent(...)

Adding Route Tracking to Existing Screen

1. Define route enum: Add YourFeatureRoute to AnalyticsConstants.swift
2. Update data model: Add route: YourFeatureRoute? parameter
3. Pass through hierarchy: Coordinator → View → ViewModel
4. Update analytics call: Pass route to existing log method

🎯 Common Patterns

Pattern 1: Screen Analytics (onAppear)

// ViewModel
final class HomeWidgetsViewModel {
    let route: HomeWidgetRoute?

    func onAppear() {
        AnytypeAnalytics.instance().logScreenWidget(route: route)
    }
}

// Analytics method (AnytypeAnalytics+Events.swift)
func logScreenWidget(route: HomeWidgetRoute?) {
    logEvent("ScreenWidget", withEventProperties: [
        AnalyticsEventsPropertiesKey.route: route?.rawValue
    ].compactMapValues { $0 })
}

// Route enum (AnalyticsConstants.swift)
enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"
    case space = "Space"
    case appLaunch = "AppLaunch"
}

Pattern 2: Button Click Analytics

// ViewModel
func onTapShare() {
    AnytypeAnalytics.instance().logClickShare(type: .link, route: .settings)
    output?.onShareSelected()
}

// Analytics method
func logClickShare(type: ShareType, route: ShareRoute) {
    logEvent("ClickShare", withEventProperties: [
        AnalyticsEventsPropertiesKey.type: type.rawValue,
        AnalyticsEventsPropertiesKey.route: route.rawValue
    ])
}

Pattern 3: Multi-Space Events

func logCreateObject(objectType: AnalyticsObjectType, spaceId: String, route: AnalyticsEventsRouteKind) {
    logEvent("CreateObject", spaceId: spaceId, withEventProperties: [
        AnalyticsEventsPropertiesKey.objectType: objectType.analyticsId,
        AnalyticsEventsPropertiesKey.route: route.rawValue
    ])
}

🗂️ Analytics File Structure

Key Files

• AnalyticsConstants.swift - All route enums, property keys (400+ lines)
• AnytypeAnalytics+Events.swift - All event methods (1,500+ lines)
• Converters/ - Domain type → analytics value converters

Route Enum Location

Always add to AnalyticsConstants.swift, grouped by feature:

// Widget-related routes
enum AnalyticsWidgetRoute: String {
    case addWidget = "AddWidget"
    case inner = "Inner"
}

enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"
    case space = "Space"
    case appLaunch = "AppLaunch"
}

// Screen navigation routes
enum SettingsSpaceShareRoute: String {
    case settings = "Settings"
    case navigation = "Navigation"
    case chat = "Chat"
}

📈 Route Tracking Implementation

Step-by-Step: Adding Route to Screen

Example: Adding route tracking to ScreenWidget

1. Define route enum (AnalyticsConstants.swift):

enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"            // Home button click
    case space = "Space"          // Space selection
    case appLaunch = "AppLaunch"  // App launch
}

2. Update data model:

struct HomeWidgetData: Hashable {
    let spaceId: String
    let route: HomeWidgetRoute?  // Add route parameter
}

3. Pass through view hierarchy:

// Coordinator
HomeWidgetsView(info: info, output: model, route: data.route)

// View
HomeWidgetsViewModel(info: info, output: output, route: route)

4. Update analytics call:

// ViewModel
func onAppear() {
    AnytypeAnalytics.instance().logScreenWidget(route: route)
}

// Analytics method
func logScreenWidget(route: HomeWidgetRoute?) {
    logEvent("ScreenWidget", withEventProperties: [
        AnalyticsEventsPropertiesKey.route: route?.rawValue
    ].compactMapValues { $0 })
}

5. Set route at navigation points:

// Home button
let data = HomeWidgetData(spaceId: spaceId, route: .home)

// Space selection
let data = HomeWidgetData(spaceId: spaceId, route: .space)

// App launch
let data = HomeWidgetData(spaceId: spaceId, route: .appLaunch)

🔧 Common Property Keys

Located in AnalyticsEventsPropertiesKey:

| Key | Usage | Example | |-----|-------|---------| | route | Navigation context | .home, .navigation, .widget | | type | Primary classification | .image, .video, .file | | objectType | Object type ID | type.analyticsType.analyticsId | | spaceId | Space identifier | document.spaceId | | count | Quantity values | Number of items | | format | Data format | File format, date format |

⚠️ Common Mistakes

❌ Hardcoded Route Strings

// WRONG
AnytypeAnalytics.instance().logScreenWidget(route: "Home")

// CORRECT
AnytypeAnalytics.instance().logScreenWidget(route: .home)

❌ Route Enum in Wrong File

// WRONG - defined in feature file
enum HomeWidgetRoute: String {
    case home = "Home"
}

// CORRECT - defined in AnalyticsConstants.swift

❌ Missing compactMapValues

// WRONG - will include nil values as NSNull
[AnalyticsEventsPropertiesKey.route: route?.rawValue]

// CORRECT - removes nil values
[AnalyticsEventsPropertiesKey.route: route?.rawValue].compactMapValues { $0 }

❌ Using String Literals for Property Keys

// WRONG
["route": route.rawValue]

// CORRECT
[AnalyticsEventsPropertiesKey.route: route.rawValue]

🔍 Finding Existing Patterns

# Search for existing events
rg "logEvent.*EventName" Anytype/Sources/Analytics/

# Find route enums
rg "enum.*Route.*String" Anytype/Sources/Analytics/AnalyticsConstants.swift

# Find property usage
rg "AnalyticsEventsPropertiesKey\." Anytype/Sources/Analytics/

# Find screen analytics
rg "func logScreen" Anytype/Sources/Analytics/AnytypeAnalytics+Events.swift

📚 Complete Documentation

Full Guide: Anytype/Sources/PresentationLayer/Common/Analytics/ANALYTICS_PATTERNS.md

For comprehensive coverage of:

• Analytics system architecture
• All analytics patterns (user actions, screen navigation, content creation)
• Route context tracking best practices
• Platform-specific considerations
• Testing analytics events
• Migration patterns for adding parameters
• Complete examples and code snippets

✅ Workflow Checklist

When adding analytics:

• [ ] Route enum added to AnalyticsConstants.swift
• [ ] Event method added to AnytypeAnalytics+Events.swift
• [ ] Used existing property keys (AnalyticsEventsPropertiesKey.*)
• [ ] Optional properties use .compactMapValues { $0 }
• [ ] Route passed through view hierarchy (if tracking navigation)
• [ ] No hardcoded strings for routes or property keys
• [ ] Followed existing naming conventions (PascalCase events, camelCase properties)

🔗 Related Skills & Docs

• ios-dev-guidelines → IOS_DEVELOPMENT_GUIDE.md - MVVM/Coordinator patterns for passing analytics data
• code-generation-developer → Understanding the build system
• design-system-developer → Tracking UI interactions

---

Navigation: This is a smart router. For deep patterns and examples, always refer to ANALYTICS_PATTERNS.md.