Press CTRL+K to open search

RFC-005: GA4 User Nudge Legacy Redirect Event Contract

  • Updated on Aug 26, 2026
  • Published on Aug 26, 2026
  • 2 minute(s) read
  • G
 Prev Next

RFC-005: GA4 User Nudge Legacy Redirect Event Contract

Related Documents

  • RFC-001: GA4 Event Contract & Reporting Alignment
  • RFC-004: GA4 Landing Page Event Contract
  • ADR-018: Typed Analytics (GA) Architecture

Abstract

This RFC defines the GA4 contract for the User Nudge call-to-action that routes users from OneCMS to the legacy platform experience.

The contract standardizes one navigation event and a minimal payload (page_key only) so product and analytics teams can measure where legacy fallback intent originates, without introducing high-cardinality URL dimensions.

1. Introduction

1.1 Background

OneCMS surfaces a User Nudge banner that allows users to switch back to the legacy platform from selected pages. Existing telemetry did not explicitly capture this transition intent.

1.2 Problem Statement

Without a dedicated event contract, the team cannot reliably answer:

From which page did users choose to return to legacy?

1.3 Goals

This RFC standardizes:

  • A canonical event name for User Nudge legacy switch interaction.
  • A minimal payload model that includes only the originating page key.
  • Trigger semantics for stable event emission behavior.
  • Governance boundaries aligned with RFC-001 and ADR-018.

2. Terminology

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

  • User Nudge: The info banner CTA that offers navigation to the legacy experience.
  • Legacy Redirect Intent: The user action of clicking the legacy switch CTA.
  • Page Key: Stable route identifier (pageKey) associated with User Nudge render context.

3. Scope

3.1 In Scope

  • GA contract for User Nudge click interaction.
  • Event naming.
  • Payload field definition.
  • Trigger semantics.

3.2 Out of Scope

  • Impression/view tracking for User Nudge.
  • Destination URL analytics dimensions.
  • Backend or GA property configuration changes.

4. Contract Specification

4.1 Canonical Event

navigation_nudge_click

4.2 Payload Requirements

Event Required Payload Fields Optional Payload Fields
navigation_nudge_click page_key —

Field Definition

  • page_key: Route key from User Nudge context (pageKey), represented as a stable identifier string.

4.3 Trigger Semantics

  • The event MUST fire when the user clicks Switch to the old experience in User Nudge.
  • The event MUST be emitted before navigation completes.
  • The event SHOULD be emitted exactly once per click interaction.

4.4 Contract Constraints

  • Payload MUST NOT include the full destination URL or query parameters.
  • Payload MUST NOT include PII.
  • Contract changes to required fields MUST be proposed in a new RFC revision.

5. Responsibilities

Engineering

Implements the typed contract, emission behavior, and tests.

Analytics

Owns GA4 dimension setup and downstream reporting.

Product

Owns interpretation of legacy fallback intent trends.

6. Versioning and Change Management

This contract inherits RFC-001 versioning rules.

  • Adding optional fields MAY be treated as non-breaking.
  • Renaming the event or required payload fields MUST be treated as a breaking change.

7. Risks and Considerations

  • If page_key usage expands without governance, low-quality or unstable keys may fragment reporting.
  • Missing instrumentation in newly enabled User Nudge surfaces can undercount fallback intent.

8. Open Questions

  • Should User Nudge impression telemetry be standardized in a future RFC for funnel conversion analysis?

9. Decision Outcome

Pending review by Engineering, Analytics, and Product.

10. References

  • RFC-001: GA4 Event Contract & Reporting Alignment
  • RFC-004: GA4 Landing Page Event Contract
  • ADR-018: Typed Analytics (GA) Architecture
  • User Nudge component
  • Navigation analytics payload map