RFC-004: GA4 Landing Page Event Contract

Related Documents:

RFC-001 (GA4 Event Contract & Reporting Alignment)
RFC-002 (GA4 Authentication Event Contract)
RFC-003 (GA4 Customer Support Event Contract)
ADR-018 (Typed Analytics Architecture)

Abstract

This RFC defines the GA4 event contract for the OneCMS Landing Page (Overview Dashboard). It standardizes widget-level events, payload semantics, and trigger behavior for navigation, content continuation, alerts, team activity, onboarding tour, organization switching, preferences, release notes, feedback, and empty-state rendering.

The contract extends RFC-001 while preserving typed, governed telemetry suitable for operational and product insights.

1. Introduction

1.1 Background

The landing page acts as the operational command center for OneCMS users. Analytics require a formal, typed contract so widget interactions are measurable without taxonomy drift.

1.2 Problem Statement

Without a dedicated landing contract, teams risk inconsistent widget event names, uncontrolled payloads, and reduced dashboard reliability.

1.3 Goals

This RFC standardizes:

Canonical landing-page event names and categories.
Payload requirements for each widget interaction.
Trigger timing for intent/state events.
Governance boundaries aligned with RFC-001.

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.

Widget Interaction: User action taken within a landing-page widget.
State Event: Event representing a UI state transition (e.g., empty state render).
Operational Outcome: success | fail | cancel represented at envelope level when relevant.

3. Scope

3.1 In Scope

Landing page events for quick access, continue-work, alerts, team activity, tour, org switch, preferences, release notes, feedback, and empty states.
Typed payload maps and category assignments.

3.2 Out of Scope

GA emitter wiring implementation in components.
Dashboard design and reporting formulas.
Backend analytics pipeline changes.

4. Landing Page Event Contract

4.1 Canonical Event Set

navigation_quick_access_click
content_resume_work_interaction
system_alert_interaction
social_team_activity_click
navigation_tour_interaction
navigation_org_switch
system_preferences_update
discovery_release_note_interaction
customer_support_feedback_submit
navigation_empty_state_view

4.2 Payload Requirements

Event	Required Payload Fields	Optional Payload Fields
`navigation_quick_access_click`	`shortcut_name`, `shortcut_index`, `is_default`, `calculation_logic`	—
`content_resume_work_interaction`	`item_category`, `item_type`, `action`, `item_rank`	—
`system_alert_interaction`	`alert_severity`, `alert_type`, `alert_title`, `action`	—
`social_team_activity_click`	`activity_action`, `asset_type`, `is_disabled`	—
`navigation_tour_interaction`	`tour_name`, `step_number`, `total_steps`, `action`	—
`navigation_org_switch`	`target_org_id`, `target_org_name`, `search_utilized`	—
`system_preferences_update`	`preference_category`, `new_value`, `previous_value`	—
`discovery_release_note_interaction`	`note_title`, `note_type`, `has_new_badge`, `interaction_type`	—
`customer_support_feedback_submit`	`feedback_type`, `text_length`	—
`navigation_empty_state_view`	`widget_name`, `display_message`	—

4.3 Contract Constraints

Event names MUST remain stable and follow <category>_<event> format.
Async operations MUST report completion semantics via envelope-level outcome.
Payloads MUST NOT include PII (email, phone, credentials, tokens, raw free-text content).
Empty-state events MUST use approved display messaging for stable reporting dimensions.

5. Event Trigger Matrix

Event	When Fired	Outcome
`navigation_quick_access_click`	User clicks quick access shortcut	success
`content_resume_work_interaction`	User resumes/views/dismisses continue-work item	success
`system_alert_interaction`	User views or dismisses needs-attention alert	success
`social_team_activity_click`	User opens team activity item	success
`navigation_tour_interaction`	User starts/steps/skips/completes guided tour	success/cancel
`navigation_org_switch`	User confirms organization switch	success/fail
`system_preferences_update`	User updates theme preference	success/fail
`discovery_release_note_interaction`	User interacts with release-note CTA	success
`customer_support_feedback_submit`	User submits write-to-us feedback	success/fail
`navigation_empty_state_view`	Widget renders approved empty state	success

6. Responsibilities

Engineering: Owns typed schema, emission semantics, normalization path, and production gating.
Analytics: Owns GA4 property config, dimension registration, and dashboard definitions.
Product: Owns behavioral questions and conversion interpretation.

7. Versioning and Change Management

This contract inherits RFC-001 versioning policy.
New optional fields/events SHOULD be treated as minor evolution.
Renaming/removing existing event fields MUST be a major contract change.
Similar interactions SHOULD extend existing taxonomy rather than creating parallel event names.

8. Risks and Considerations

Widget UX changes can invalidate payload assumptions if type unions are not updated.
Free-form strings in shortcut_name, alert_title, and note_title can fragment analytics if not normalized.
Over-emitting state events can create noisy dashboards.

9. Open Questions

Should release-note and feedback widgets be formalized as required landing modules?
Should organization switch event include old org context for transition analysis?
Should empty-state tracking include is_default_fallback for renderer-level diagnostics?

10. Decision Outcome

Pending review by Engineering, Analytics, and Product.

11. References

RFC-001: GA4 Event Contract & Reporting Alignment
RFC-002: GA4 Authentication Event Contract
RFC-003: GA4 Customer Support Event Contract
ADR-018: Typed Analytics (GA) Architecture
Landing page GA matrix (working draft)
Overview landing page route