feat(builder): add network context to wizard, export and sidebar analytics events

[pasevin]

Summary

Audit + gap fill of the UI Builder GA4 events ahead of registering event-scoped custom dimensions. No new event types; existing param names are unchanged.

• wizard_step, export_clicked, sidebar_interaction now include network_id and ecosystem.
• All string dimensions are normalised to "unknown" when missing/empty (central orUnknown / networkParams helpers in useBuilderAnalytics.ts).
• WizardLayout takes an optional analyticsContext prop (fed from the builder store in UIBuilder/index.tsx) so the common component stays store-agnostic; MainActions reads selectedNetworkConfigId/selectedEcosystem via useUIBuilderStore.
• New component tests assert exactly one event per user action for wizard Next/Back and sidebar Import/Export.
• ANALYTICS_FEATURE_FLAG.md now carries the full event → params table.

Event → params table

Event	Parameters	Fires when	Call site
page_view	page_title, page_location (GA defaults)	Once on load, automatically via gtag('config'); no manual trackPageView calls	AnalyticsProvider in App.tsx
ecosystem_selected	ecosystem	Ecosystem chosen in chain selector, or deep link changes ecosystem	ChainSelector.tsx, useBuilderLifecycle.ts
network_selected	network_id, ecosystem	Network chosen, or deep link resolves a network	ChainSelector.tsx, useBuilderLifecycle.ts
wizard_step	step_number, step_name, network_id ✨, ecosystem ✨	Once per Next/Back click (step being entered)	Common/WizardLayout.tsx
export_clicked	export_type, network_id ✨, ecosystem ✨	Once after app export succeeds	hooks/useCompleteStepState.ts
sidebar_interaction	action, network_id ✨, ecosystem ✨	Once per sidebar Import/Export click	Sidebar/AppSidebar/MainActions.tsx
transaction_executed	network_id, ecosystem, execution_method	Tx succeeds from form preview	StepFormCustomization/FormPreview.tsx
contract_ui_created	network_id, ecosystem, total_records	New Contract UI record first persisted	hooks/builder/useAutoSave.ts
relayer_service_configured	network_id, ecosystem	Once per mount when URL + API key + relayer are set	RelayerConfiguration/index.tsx
uikit_changed	network_id, ecosystem, uikit_name	UI kit selected in settings	UiKitSettings.tsx
address_book_opened	network_id, ecosystem	Dialog opens (false → true only)	AddressBook/AddressBookDialog.tsx

✨ = added in this PR. Custom dimensions to register: ecosystem, network_id, step_name, step_number, export_type, action, execution_method, uikit_name, total_records.

Audit findings

• No double fires. The two trackWizardStep calls in WizardLayout.tsx are the Next and Back handlers; each fires once per click. relayer_service_configured and address_book_opened are ref-guarded; contract_ui_created only fires on the CREATE path; ecosystem_selected from deep links is guarded by a change check.
• page_view is not double-counted. gtag('config', tagId) is called without send_page_view: false, so GA sends one automatic page_view, and nothing in apps/builder calls trackPageView (the hook only passes it through). No fix needed.
• Empty/undefined values. Previously only contract_ui_created/address_book_opened had 'unknown' fallbacks; the hook now applies them uniformly.
• Not changed (noted): programmatic step changes (deep-link auto-advance via pendingNetworkId, sidebar record load) bypass WizardLayout's Next/Back handlers and therefore do not emit wizard_step. This matches the "user clicked" semantics of the event; flagging in case a step-entered metric is wanted later.
• export_type is still hard-coded to react-vite (the only template today).

Verification

• pnpm lint, pnpm typecheck (builder) — clean
• pnpm test (repo root) — 49 files / 335 tests builder, all other packages pass

[Copilot]

Pull request overview

Adds network and ecosystem context to UI Builder analytics events, normalizes missing values, and expands test coverage and documentation.

Changes:

• Extended wizard, export, and sidebar analytics payloads.
• Added fallback normalization and analytics tests.
• Updated the GA4 event documentation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
apps/builder/src/hooks/useBuilderAnalytics.ts	Adds analytics context and fallback handling.
apps/builder/src/hooks/__tests__/useBuilderAnalytics.test.ts	Tests context and fallback behavior.
apps/builder/src/components/UIBuilder/index.tsx	Supplies wizard analytics context.
apps/builder/src/components/UIBuilder/hooks/useCompleteStepState.ts	Adds export network context.
apps/builder/src/components/Sidebar/AppSidebar/MainActions.tsx	Adds sidebar network context.
apps/builder/src/components/Sidebar/AppSidebar/__tests__/MainActions.analytics.test.tsx	Tests sidebar analytics events.
apps/builder/src/components/Common/WizardLayout.tsx	Adds wizard analytics context propagation.
apps/builder/src/components/Common/__tests__/WizardLayout.analytics.test.tsx	Tests wizard event behavior.
apps/builder/ANALYTICS_FEATURE_FLAG.md	Documents the complete event parameter table.

Suppressed comments (1)

apps/builder/src/hooks/useBuilderAnalytics.ts:62

• The normalization guarantee in the new documentation/PR contract does not cover network_selected: this hook only overrides trackEcosystemSelection, while trackNetworkSelection is still the method inherited through ...analytics. If the shared hook receives an empty network ID or ecosystem, those values can still be sent without the unknown fallback. Wrap this method here (preserving the shared analytics gating) or otherwise ensure it applies the same normalization, and add a regression test for empty inputs.

      trackEcosystemSelection: (ecosystem: string) => {
        analytics.trackEvent('ecosystem_selected', { ecosystem: orUnknown(ecosystem) });

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.