RFC-003: GA4 Customer Support Event Contract

RFC-003: GA4 Customer Support Event Contract

Related Documents:

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

Abstract

This RFC specifies the GA4 event contract for the Customer Support module in OneCMS. It defines canonical events, payload constraints, and trigger semantics for search, customer detail exploration, quick actions, and support session lifecycle.

The contract is designed to support operational intelligence (agent workflows, friction points, and handling patterns) while remaining compliant with the global GA contract in RFC-001.

1. Introduction

1.1 Background

Customer Support workflows are operational and multi-step. Simple click telemetry is insufficient for understanding agent efficiency and friction. A typed contract is needed for stable reporting and predictable evolution.

1.2 Problem Statement

Without a dedicated contract, teams risk:

• inconsistent event dimensions across list/detail flows,
• unbounded strings for tabs/actions causing taxonomy drift,
• ambiguous outcome interpretation for async operations.

1.3 Goals

This RFC standardizes:

1. Canonical customer support event names.
2. Typed payload requirements and controlled dimensions.
3. Trigger points across list and detail journeys.
4. Async outcome semantics aligned with RFC-001 envelope model.

2. Terminology

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

• Operational Event: Event representing agent workflow progression.
• Quick Action: Immediate support intervention (profile/subscription/billing action).
• Session Lifecycle: Start/restore/save/end of a support handling session.

3. Scope

3.1 In Scope

• Customer Support list route and detail route event contracts.
• Typed payload map under customer_support analytics category.
• Journey stages: search, discover, inspect, act, session lifecycle.

3.2 Out of Scope

• GA emitter wiring implementation.
• Dashboard/KPI design.
• Backend data pipeline changes.

4. Customer Support Event Contract

4.1 Canonical Event Set

• customer_search
• customer_search_filter_change
• customer_search_result_open
• customer_search_pagination
• customer_search_external_id_detected
• customer_detail_view
• customer_detail_tab_change
• customer_quick_action_open
• customer_quick_action_submit
• customer_session_restore
• customer_session_start
• customer_session_save
• customer_session_end
• customer_add_user_open
• customer_add_user_submit

Event Naming Rules

• Event names MUST be user/workflow-centric and action/state-oriented.
• Event names MUST use snake_case and remain stable after production adoption.
• Result events MUST represent business outcomes, not low-level technical steps.

4.2 Payload Requirements

4.3 Contract Constraints

• Async operational events MUST use envelope-level outcome (success | fail | cancel).
• If an event represents completion of an asynchronous operation, it MUST be emitted only after the operation result is known.
• Payloads MUST NOT encode implicit outcome logic.
• Controlled dimensions (tab, action_name, filter) MUST remain aligned with source registries/config.
• Customer Support events MUST NOT include PII (email, phone, tokens, or raw user-entered search values).

5. Event Trigger Matrix

ℹ️ Note
For synchronous state-transition events (for example filter change, pagination, and tab switch), success indicates a valid state change, not backend operation completion.

6. Responsibilities

• Engineering: emit typed events at agreed trigger points, preserve controlled dimensions, and enforce PII boundaries.
• Product: define operational workflow questions and success criteria.
• Analytics: maintain dashboards and dimension compatibility across schema versions.

7. Versioning and Change Management

• This contract inherits versioning policy from RFC-001.
• Adding new optional fields/events SHOULD be a minor change.
• Renaming/removing required fields or controlled dimension values MUST be a major contract change.
• New events SHOULD extend existing workflow stages instead of introducing parallel taxonomy for equivalent actions.
• Contract-breaking changes MUST be proposed through a new RFC referencing RFC-003.

8. Risks and Considerations

• Registry drift can desynchronize controlled dimensions and emitted payloads.
• Over-instrumentation can dilute actionability.
• Inconsistent error_code normalization can weaken fail-path analysis.

9. Open Questions

1. Should we add customer_detail_section_view for non-tab modules in future layouts?
2. Should session lifecycle include explicit pause/resume events?
3. Should we define a shared error_code dictionary for all support actions?

10. Decision Outcome

• Accepted and implemented by Engineering, Product, and Analytics.

11. References

• RFC-001: GA4 Event Contract & Reporting Alignment
• RFC-002: GA4 Authentication Event Contract
• ADR-018: Typed Analytics (GA) Architecture
• Customer support analytics types
• Customer support GA matrix (working draft)
• Customer Support DebugView QA checklist

12. Document History