Analytics (analytics_gen, YAML as SSOT)

When to use

• Adding a new event for a feature or flow.
• Changing event parameters or event names.
• Validating analytics changes before a PR/commit.
• Instrumenting a BLoC/UI with type-safe analytics calls.

Steps

1) Define events in YAML

Create or update mobile/events/<domain>.yaml.

Example:

orders:
  screen_opened:
    description: User opened the orders screen.
    event_name: "Orders: Screen Opened"

  filter_applied:
    description: User applied a filter on the orders list.
    event_name: "Orders: Filter Applied"
    parameters:
      filter_type: string
      has_results: bool
      applied_count: int?

Rules of thumb:

• YAML keys are snake_case.
• Prefer required parameters; use optional (?) only when data can truly be missing.
• Deprecate with deprecated: true rather than deleting.

2) Generate code and docs

dart run analytics_gen:generate --docs --exports

3) Validate before commit

dart run analytics_gen:generate --validate-only

4) Use generated methods (no manual event strings)

analytics.logOrdersScreenOpened();

analytics.logOrdersFilterApplied(
  filterType: 'status',
  hasResults: true,
  appliedCount: 2,
);

5) Where to log

Prefer logging at the orchestration layer:

• BLoC event handlers (user intent → side effects)
• scopes/controllers that represent user actions

Avoid logging inside low-level clients/datasources.