RFC-006: GA4 AppCMS Event Contract

RFC-006: GA4 AppCMS Event Contract

Related Documents

• RFC-001: GA4 Event Contract and Reporting Alignment
• RFC-002: GA4 Authentication Event Contract
• RFC-003: GA4 Customer Support Event Contract
• RFC-004: GA4 Landing Page Event Contract
• ADR-018: Typed Analytics Architecture

Abstract

This RFC defines the GA4 analytics contract for AppCMS across Settings, Brand and Theme, Logo and Images, and Service.

It standardizes canonical event names, shared launch semantics, payload constraints, and outcome behavior for asynchronous operations. The contract is designed to eliminate duplicate publish/launch telemetry, stabilize reporting dimensions, and provide a single analytics governance surface for AppCMS.

1. Introduction

1.1 Background

AppCMS currently spans multiple high-impact modules with heterogeneous interaction patterns and asynchronous persistence paths. Prior module-level analytics planning identified a shared launch flow and several module-specific event families that require a unified contract.

1.2 Problem Statement

Without a dedicated AppCMS contract, teams face:

• Duplicate launch/publish events across modules.
• Inconsistent payload dimensions for similar operations.
• Unstable dashboards caused by uncontrolled dimension values.
• Ambiguous async outcome interpretation for save/load/resize-style operations.

1.3 Goals

This RFC standardizes:

• A single cross-module AppCMS launch contract.
• Module-specific canonical event catalogs.
• Controlled payload dictionaries for high-cardinality dimensions.
• Normative outcome semantics and PII-safe constraints.
• A freeze-ready event baseline for RFC-006 implementation planning.

2. Terminology

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

• AppCMS Module: One of settings, brand_theme, logo_images, or service.
• Shared Launch Flow: The common AppCMS publish/launch path used across modules.
• Outcome Event: Event that represents the final async result with envelope-level outcome (success, fail, cancel).
• No-op Exit: Path where no persistence attempt is made, for example, a field is not dirty or required context is missing.
• Controlled Dimension: A payload field whose values are bounded to a stable enum.

3. Scope

3.1 In Scope

AppCMS analytics event contract for:

• settings
• brand_theme
• logo_images
• service

The contract covers:

• Canonical event names.
• Shared envelope semantics.
• Required payload dimensions.
• Outcome handling for asynchronous operations.
• Cross-module launch behavior.

3.2 Out of Scope

The contract does not define:

• Dashboard layout and reporting UI.
• Implementation-specific React internals.
• Backend response shape beyond analytics payload requirements.
• Backend telemetry transport internals beyond envelope and payload contract constraints.

4. Contract Specification

4.1 Contract Boundary

This contract standardizes analytics events for AppCMS across the following modules:

• settings
• brand_theme
• logo_images
• service

The contract defines:

• Canonical event names.
• Shared envelope semantics.
• Required payload dimensions.
• Outcome handling for asynchronous operations.
• Cross-module launch behavior.

The contract does not define:

• Dashboard layout and reporting UI.
• Implementation-specific React internals.
• Backend response shape beyond analytics payload requirements.

4.2 Event Naming and Envelope

4.2.1 Naming

• Event keys MUST use snake_case.
• Event keys SHOULD remain stable after production rollout.
• Envelope-level identity follows category_event at GA transport.

Examples:

• appcms_launch_result
• settings_save
• brand_theme_save
• logo_images_asset_resize
• service_save

4.2.2 Envelope Expectations

All AppCMS events MUST comply with the global typed analytics envelope defined by RFC-001 and ADR-018.

Required common context:

• category
• event
• schema_version
• site
• siteId
• env

Optional common context:

• outcome — required for async result events.
• userId — when available under platform policy.

4.3 Shared Cross-Module Launch Contract

Launch/publish is shared across all AppCMS modules and MUST be modeled once.

4.3.1 Shared Events

4.3.2 Dedupe Rule

Module-specific publish events MUST NOT be added when they represent the same shared launch flow.

module_context MUST be used for module-level segmentation.

4.4 Module Event Catalog

4.4.1 Settings

Critical:

Good-to-have:

• settings_namespace_close
• settings_version_history_paginate
• settings_datamap_row_add
• settings_datamap_row_remove
• settings_tve_manage_open
• settings_tve_provider_reorder
• settings_tve_provider_delete_confirm
• settings_button_action_triggered

4.4.2 Brand and Theme

Critical:

Good-to-have:

• brand_theme_use_default_toggle
• brand_theme_font_list_load
• brand_theme_network_context_change

4.4.3 Logo and Images

Critical:

Good-to-have:

• logo_images_asset_library_search
• logo_images_resize_required_shown
• logo_images_asset_library_retry

4.4.4 Service

Critical:

Good-to-have:

• service_domain_add_click
• service_domain_remove_init
• service_domain_remove_confirm
• service_domain_remove_cancel
• service_monetization_type_toggle
• service_type_select

4.5 Controlled Dimension Dictionary

These dimensions SHOULD use controlled values to avoid cardinality drift.

4.6 Emission Workflow and State Semantics

4.6.1 View and Load

• View events MUST emit on module entry/render.
• Async load events MUST emit success/fail semantics only after the result is known.

4.6.2 Save

• Save events MUST emit only when an actual persistence attempt is executed.
• No-op exits MUST NOT be emitted as fail.
• No-op exits MAY be tracked later as cancel with a bounded skipped_reason dictionary.

4.6.3 Launch

• appcms_launch_intent MUST emit when launch is explicitly triggered.
• appcms_launch_result MUST emit once the final launch result is known.
• Failure results SHOULD include both error_code and error_count when available.

4.7 Normative Requirements

• Event naming MUST be snake_case.
• Shared launch tracking MUST use appcms_launch_intent and appcms_launch_result only.
• Duplicate module-specific publish events for shared launch MUST NOT be introduced.
• Async result events MUST carry envelope-level outcome.
• Fail outcomes MUST include error_code when available.
• Payloads MUST NOT include PII, including email, phone, credentials, tokens, or unbounded free text.
• High-cardinality dimensions SHOULD be bucketed or constrained.
• Contract-breaking changes MUST be proposed through a new RFC revision flow.

4.8 Freeze Baseline for RFC-006

Critical freeze baseline:

• appcms_launch_intent
• appcms_launch_result
• settings_view
• settings_namespace_open
• settings_namespace_load
• settings_save
• settings_version_history_view
• brand_theme_view
• brand_theme_platform_switch
• brand_theme_section_switch
• brand_theme_save
• logo_images_view
• logo_images_platform_switch
• logo_images_asset_library_load
• logo_images_asset_apply
• logo_images_asset_upload_process
• logo_images_asset_delete
• logo_images_asset_resize
• service_view
• service_load
• service_save

Good-to-have freeze baseline:

• settings_namespace_close
• settings_version_history_paginate
• settings_datamap_row_add
• settings_datamap_row_remove
• settings_tve_manage_open
• settings_tve_provider_reorder
• settings_tve_provider_delete_confirm
• settings_button_action_triggered
• brand_theme_use_default_toggle
• brand_theme_font_list_load
• brand_theme_network_context_change
• logo_images_asset_library_search
• logo_images_resize_required_shown
• logo_images_asset_library_retry
• service_domain_add_click
• service_domain_remove_init
• service_domain_remove_confirm
• service_domain_remove_cancel
• service_monetization_type_toggle
• service_type_select

5. Responsibilities

Engineering

Engineering owns:

• Typed event schema.
• Emission timing.
• Payload normalization.
• PII-safe enforcement in implementation.

Analytics

Analytics owns:

• GA4 registration.
• Report compatibility.
• Schema-version-aware interpretation.

Product

Product owns:

• Behavior questions.
• Event prioritization.
• Interpretation of critical versus good-to-have telemetry.

6. Versioning and Change Management

This contract inherits the versioning principles from RFC-001.

• Adding optional events or optional dimensions SHOULD be treated as minor evolution.
• Renaming or removing existing event names or required dimensions MUST be treated as a major change.
• Contract-breaking changes MUST be proposed in a new RFC that references RFC-006.
• During migration, dual-emit strategies SHOULD be considered where dashboard continuity is required.

7. Risks and Considerations

• Inconsistent controlled dimension values can fragment reporting and reduce comparability.
• Emitting save failures for no-op exits can artificially inflate operational failure rates.
• Module-level experimentation can introduce ungoverned event variants if taxonomy controls are not enforced.
• Shared launch instrumentation can regress into duplicate events if module-local publish naming is reintroduced.

8. Open Questions

• Should no-op save exits be permanently ignored, or standardized later as cancel with skipped_reason?
• Should load events remain result-only, or split into start and result pairs for latency analysis?
• Should logo_images_resize_required_shown move from good-to-have to critical due to UX correctness dependency?
• Should service domain-intent events be promoted to critical for churn diagnostics?

9. Decision Outcome

Pending review by Engineering, Product, and Analytics.

10. References

• RFC-001: GA4 Event Contract and Reporting Alignment
• RFC-002: GA4 Authentication Event Contract
• RFC-003: GA4 Customer Support Event Contract
• RFC-004: GA4 Landing Page Event Contract
• ADR-018: Typed Analytics Architecture