Setting Up the Analytics SDK

What you'll learn

• Generating the Analytics SDK with Firebase Analytics implementation
• Understanding the multi-vendor analytics abstraction
• Logging events, screen views, and user properties
• Swapping or combining analytics providers

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Firebase configured in your project (for the default Firebase Analytics impl)

Step 1: Generate the Analytics SDK

archipelago generate analytics_sdk

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• isForMonorepo — true

Or use a config file:

{
  "appName": "MyApp",
  "isForMonorepo": true
}

archipelago generate analytics_sdk --config analytics_config.json

Step 2: Understand the Generated Structure

The Analytics SDK uses the API/Impl split for vendor-agnostic event tracking:

infrastructure/
├── analytics_sdk_api/
│   └── lib/src/
│       ├── analytics_client.dart          # Abstract analytics contract
│       ├── analytics_event.dart           # Event model
│       └── analytics_user_property.dart   # User property model
└── analytics_sdk_impl/
    └── lib/src/
        ├── firebase_analytics_client.dart # Firebase implementation
        ├── composite_analytics_client.dart # Fan-out to multiple providers
        └── di/
            └── analytics_module.dart      # DI registration

Step 3: Register the Analytics SDK

In your shell app's bootstrap.dart, register analytics during initialization:

import 'package:analytics_sdk_impl/analytics_sdk_impl.dart';

// Single provider
getIt.registerSingleton<AnalyticsClient>(
  FirebaseAnalyticsClient(),
);

// Or fan-out to multiple providers
getIt.registerSingleton<AnalyticsClient>(
  CompositeAnalyticsClient([
    FirebaseAnalyticsClient(),
    // MixpanelAnalyticsClient(),
  ]),
);

Step 4: Track Events

Features depend on analytics_sdk_api only and log events through the abstraction:

final analytics = getIt<AnalyticsClient>();

// Track a custom event
await analytics.logEvent(AnalyticsEvent(
  name: 'purchase_completed',
  parameters: {'amount': 99.99, 'currency': 'USD'},
));

// Track screen views
await analytics.logScreenView(screenName: 'ProductDetail');

// Set user properties
await analytics.setUserProperty(
  name: 'subscription_tier',
  value: 'pro',
);

Key Customization Points

Customization	Where to Change
Add Mixpanel/Amplitude	Create new AnalyticsClient impl, add to composite
Filter events per provider	CompositeAnalyticsClient — add provider-specific filtering
Add default parameters	FirebaseAnalyticsClient — enrich events before sending
Disable in debug mode	analytics_module.dart — register noop impl for debug builds

Next Steps

• Set up feature flags to gate analytics events
• Configure monitoring to track analytics failures