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.