analytics-events

Analytics Event Rules — flutter_core_modules

EventEntity Subclass Structure

All analytics events are Dart classes extending EventEntity:

// Minimum required shape
class MyEvent extends EventEntity {
  const MyEvent();

  @override
  Map<String, Object>? get properties => const {};
}

// With properties
class MyEventWithData extends EventEntity {
  final String itemId;
  final double amount;

  const MyEventWithData({required this.itemId, required this.amount});

  @override
  Map<String, Object>? get properties => {
    'item_id': itemId,
    'amount': amount,
  };
}

Event Naming — Automatic from Class Name

Do NOT override name. The event name is derived automatically from runtimeType.toString() converted to snake_case:

TapOnReviewButton       → 'tap_on_review_button'
ChangeLanguageTo        → 'change_language_to'
OnSyncPurchasesCallback → 'on_sync_purchases_callback'

Class names must be:

• PascalCase Dart classes
• Descriptive of the action or event (not Event1, Clicked, etc.)
• Prefixed with TapOn for UI tap events

Property Value Types

Properties map String keys to Object values. Allowed value types:

• String
• num / int / double
• bool
• Map<String, Object> (nested)
• List<Object> (items must also be one of these types)

// CORRECT
@override
Map<String, Object>? get properties => {
  'plan_id': planId,        // String
  'price': price,           // double
  'is_annual': isAnnual,    // bool
  'locale': {               // nested Map
    'languageCode': locale.languageCode,
  },
};

// WRONG — avoid nullable values in properties map
@override
Map<String, Object>? get properties => {
  'value': maybeNull ?? 'unknown', // use conditional inclusion instead
};

// CORRECT — conditionally include nullable values
@override
Map<String, Object>? get properties => {
  if (label != null) 'label': label!,
  if (title != null) 'title': title!,
};

Tracking Events

// From BuildContext (widget or static method):
MyEvent().track(context: context);

// With properties:
MyEventWithData(itemId: 'abc', amount: 9.99).track(context: context);