mobile-wallet/core-base/analytics/README.md

:core-base:analytics module

Overview

The base analytics library provides a comprehensive foundation for tracking user interactions, performance metrics, and business events across all platforms in a Kotlin Multiplatform project. This module offers type-safe analytics with extensive validation, testing utilities, and performance tracking capabilities.

Enhanced Analytics Events

• Type-Safe Parameters: Automatic validation of parameter keys (≤40 chars) and values (≤100 chars)
• Builder Pattern: Fluent API for event creation with withParam() and withParams()
• 25+ Predefined Event Types: From navigation to authentication, forms to performance tracking
• Comprehensive Parameter Keys: 40+ standardized parameter keys for consistent tracking

Powerful Analytics Interface

• Multiple Convenience Methods: Simplified logging with logEvent() overloads
• Built-in Common Events: logScreenView(), logButtonClick(), logError(),logFeatureUsed()
• User Management: Support for setUserProperty() and setUserId()
• Platform Abstraction: Works seamlessly across Android, iOS, Desktop, and Web

Advanced Extension Functions

• Event Builders: Factory methods for creating common events with validation
• Performance Timing:
  • startTiming() and timeExecution() for measuring operation durations
  • TimedEvent class for manual timing control
• Batch Processing: AnalyticsBatch for efficient multiple event logging
• Safe Parameter Creation: Robust validation helpers for dynamic data

Jetpack Compose Integration

• Declarative Tracking: TrackScreenView() composable for automatic screen analytics
• Modifier Extensions: Modifier.trackClick() for effortless interaction tracking
• Lifecycle Tracking: TrackComposableLifecycle() for component enter/exit analytics
• Helper Functions: rememberAnalytics() for easy composition local access

Performance Monitoring

• Operation Timing: Comprehensive timing utilities with automatic slow operation detection
• Memory Tracking: Real-time memory usage monitoring with automatic warnings
• App Lifecycle: Track app launch times, background/foreground transitions
• Performance Statistics: Percentile-based performance analysis (P95, P99)

Testing & Validation

• Test Analytics Helper: Complete event capture and verification for unit tests
• Mock Analytics: Network delay and failure simulation for robust testing
• Data Validation: Comprehensive validation against analytics platform constraints
• Sanitization: Automatic data cleaning for invalid parameters

Platform Support

• ✅ Android: Full Firebase Analytics integration
• ✅ iOS: Firebase Analytics via nonJsCommonMain
• ✅ Desktop: Development-friendly stub implementation
• ✅ Web (JS): Configurable Firebase/stub implementation
• ✅ Native: Firebase Analytics support

📖 Usage Examples

Basic Event Logging

// Simple event
analyticsHelper.logEvent("button_clicked", "button_name" to "save")

// Using convenience methods
analyticsHelper.logScreenView("UserProfile")
analyticsHelper.logButtonClick("edit_profile", "UserProfile")
analyticsHelper.logError("Network error", "NET_001", "UserProfile")

// Builder pattern
val event = AnalyticsEvent("form_submitted")
    .withParam("form_name", "user_registration")
    .withParam("field_count", "8")
    .withParam("completion_time", "120s")
analyticsHelper.logEvent(event)

Performance Tracking

// Time a suspend function
val data = analyticsHelper.timePerformance("api_call") {
    apiService.fetchUserData()
}

// Manual timing
val timer = analyticsHelper.startTiming("data_processing")
processData()
timer.complete()

// Memory monitoring
val memoryTracker = analyticsHelper.memoryTracker()
memoryTracker.logMemoryUsage("after_data_load")

Compose Integration

@Composable
fun UserProfileScreen() {
    TrackScreenView("UserProfile")

    val analytics = rememberAnalytics()

    Button(
        modifier = Modifier.trackClick("edit_profile", analytics, "UserProfile"),
        onClick = { /* edit profile */ }
    ) {
        Text("Edit Profile")
    }
}

Batch Processing

analyticsHelper.batch()
    .add("user_registered", "user_id" to "12345")
    .add("email_verified", "verification_method" to "link")
    .add("profile_completed", "completion_percentage" to "100")
    .flush()

Testing

@Test
fun testAnalyticsTracking() {
    val testAnalytics = createTestAnalyticsHelper()

    // Use your component with test analytics
    userService.registerUser("john@example.com", testAnalytics)

    // Verify analytics were logged
    testAnalytics.assertEventLogged(
        "user_registered",
        mapOf("email_domain" to "example.com")
    )
    testAnalytics.assertEventCount("user_registered", 1)

    // Check specific events
    assert(testAnalytics.hasEvent("email_verification_sent"))
}

Data Validation

// Automatic validation and sanitization
val validatingAnalytics = analyticsHelper.withValidation(
    strictMode = false, // Sanitize invalid data instead of throwing
    logValidationErrors = true
)

// This will be automatically sanitized if invalid
validatingAnalytics.logEvent("user-action-with-invalid-chars", "param" to "value")

// Manual validation
val event = AnalyticsEvent("my_event", listOf(Param("key", "value")))
val result = event.validate()
if (!result.isValid) {
    println("Validation errors: ${result.errors}")
}

🏗️ Architecture

Core Components

1. AnalyticsEvent: Type-safe event representation with builder pattern
2. AnalyticsHelper: Platform-agnostic analytics interface
3. Platform Implementations:
   • FirebaseAnalyticsHelper for production
   • StubAnalyticsHelper for development
   • NoOpAnalyticsHelper for testing
4. Extension Functions: Utility methods for common operations
5. Validation Layer: Data quality assurance
6. Testing Utilities: Comprehensive test support

Design Principles

• Type Safety: Compile-time safety for analytics parameters
• Platform Agnostic: Write once, track everywhere
• Performance Conscious: Minimal overhead with batch processing
• Developer Friendly: Rich testing and debugging tools
• Extensible: Easy to add custom tracking methods

🔧 Integration

Dependencies

// In your module's build.gradle.kts
dependencies {
    implementation(projects.coreBase.analytics)

    // Platform-specific dependencies are handled automatically
}

Dependency Injection (Koin)

val analyticsModule = module {
    // The actual implementation is provided by platform-specific modules
    // Android: FirebaseAnalyticsHelper
    // Desktop: StubAnalyticsHelper
    // etc.
}

Compose Setup

@Composable
fun App() {
    val analytics: AnalyticsHelper = koinInject()

    CompositionLocalProvider(
        LocalAnalyticsHelper provides analytics
    ) {
        // Your app content
    }
}

📋 Event Types Reference

Navigation Events

• SCREEN_VIEW, SCREEN_TRANSITION

User Interactions

• BUTTON_CLICK, MENU_ITEM_SELECTED, SEARCH_PERFORMED, FILTER_APPLIED

Form Events

• FORM_STARTED, FORM_COMPLETED, FORM_ABANDONED, FIELD_VALIDATION_ERROR

Content Events

• CONTENT_VIEW, CONTENT_SHARED, CONTENT_LIKED

Error Events

• ERROR_OCCURRED, API_ERROR, NETWORK_ERROR

Performance Events

• APP_LAUNCH, APP_BACKGROUND, APP_FOREGROUND, LOADING_TIME

Authentication Events

• LOGIN_ATTEMPT, LOGIN_SUCCESS, LOGIN_FAILURE, LOGOUT, SIGNUP_ATTEMPT, SIGNUP_SUCCESS

Feature Usage

• FEATURE_USED, TUTORIAL_STARTED, TUTORIAL_COMPLETED, TUTORIAL_SKIPPED

🔒 Privacy & Compliance

• No PII Logging: Framework prevents logging of personally identifiable information
• Data Validation: Automatic parameter validation prevents sensitive data leakage
• Configurable: Easy to disable or mock for privacy-compliant testing
• Transparent: All logged data is visible and controllable

🚀 Performance Characteristics

• Minimal Overhead: Event creation is lightweight with lazy validation
• Batch Processing: Efficient bulk event logging
• Memory Conscious: Automatic memory usage monitoring and warnings
• Network Optimized: Platform implementations handle network efficiency

🧪 Testing Features

• Complete Event Capture: Test helpers capture all analytics for verification
• Assertion Helpers: Rich assertion methods for common verification patterns
• Mock Analytics: Simulate network conditions and failures
• Debug Output: Pretty-print analytics events for debugging

This module provides the foundation for comprehensive analytics tracking while maintaining code quality, performance, and developer experience across all platforms.

📚 API Documentation

All classes and methods in this module are comprehensively documented with KDoc. The documentation includes:

Core API Classes

• AnalyticsEvent: Type-safe event representation with builder pattern and validation
• AnalyticsHelper: Platform-agnostic analytics interface with convenience methods
• Param: Validated parameter class with automatic constraint checking
• Types: Standard event type constants organized by category
• ParamKeys: Standard parameter key constants for consistency

Extension Functions

• **AnalyticsExtensions **: Builder functions, timing utilities, and batch processing
• **PerformanceTracker **: Advanced performance monitoring and timing utilities
• UiHelpers: Jetpack Compose integration helpers

Implementations

• *FirebaseAnalyticsHelper **: Production Firebase Analytics implementation
• **StubAnalyticsHelper **: Development implementation with console logging
• **NoOpAnalyticsHelper **: No-operation implementation for testing

Testing & Validation

• TestingUtils: Comprehensive testing utilities and mock implementations
• ValidationUtils: Data validation and sanitization utilities

Documentation Features

• ✅ Detailed Descriptions: Every class and method has comprehensive documentation
• ✅ Parameter Documentation: All parameters documented with @param tags
• ✅ Usage Examples: @sample blocks with practical code examples
• ✅ Cross-References: @see tags linking related functionality
• ✅ Platform Notes: Platform-specific behavior and constraints documented
• ✅ Error Conditions: Exception throwing conditions clearly documented
• ✅ Since Tags: Version information for API tracking