Module: TrackRelay::Validators::Ga4Constraints

Defined in:
lib/track_relay/validators/ga4_constraints.rb

Overview

Enforces Google Analytics 4 naming + sizing constraints on catalog entries. Used by CatalogValidator at catalog-load time so GA4-incompatible events fail fast in development rather than silently in production where GA4 would just drop them.

Rules implemented (per GA4 docs):

  • Event names: snake_case, start with a lowercase letter, max 40 chars, not in GA4_RESERVED_NAMES.

  • Param names: same regex + max 40 chars.

  • Per-event param count: <= 25 custom params.

All violations raise Ga4ConstraintError with a message naming the offender so error messages stay actionable.

Constant Summary collapse

NAME_PATTERN =

GA4 names must start with a lowercase letter and contain only lowercase letters, digits, and underscores after that.

/\A[a-z][a-z0-9_]*\z/
MAX_NAME_LENGTH =

GA4 caps custom event/param name length at 40 characters.

40
MAX_PARAMS_PER_EVENT =

GA4 caps custom params per event at 25.

25

Class Method Summary collapse

Class Method Details

.validate_event_name!(name) ⇒ void

This method returns an undefined value.

Parameters:

  • name (Symbol, String) —

    event name to validate

Raises:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/track_relay/validators/ga4_constraints.rb', line 37

def validate_event_name!(name)
  as_string = name.to_s

  unless as_string.match?(NAME_PATTERN)
    raise Ga4ConstraintError,
      "Event name #{name.inspect} must be snake_case (matches #{NAME_PATTERN.inspect})"
  end

  if as_string.length > MAX_NAME_LENGTH
    raise Ga4ConstraintError,
      "Event name #{name.inspect} exceeds GA4 max length of #{MAX_NAME_LENGTH} chars (got #{as_string.length})"
  end

  if TrackRelay::GA4_RESERVED_NAMES.include?(as_string)
    raise Ga4ConstraintError,
      "Event name #{name.inspect} is reserved by GA4 (https://support.google.com/analytics/answer/9234069) — pick a non-reserved name"
  end
end

.validate_param_count!(params) ⇒ void

This method returns an undefined value.

Parameters:

  • params (Hash) —

    params hash from an EventDefinition

Raises:



59
60
61
62
63
64
 
# File 'lib/track_relay/validators/ga4_constraints.rb', line 59

def validate_param_count!(params)
  if params.size > MAX_PARAMS_PER_EVENT
    raise Ga4ConstraintError,
      "Event has #{params.size} custom params; GA4 caps custom params per event at #{MAX_PARAMS_PER_EVENT}"
  end
end

.validate_param_name!(name) ⇒ void

This method returns an undefined value.

Parameters:

  • name (Symbol, String) —

    param name to validate

Raises:



70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/track_relay/validators/ga4_constraints.rb', line 70

def validate_param_name!(name)
  as_string = name.to_s

  unless as_string.match?(NAME_PATTERN)
    raise Ga4ConstraintError,
      "Param name #{name.inspect} must be snake_case (matches #{NAME_PATTERN.inspect})"
  end

  if as_string.length > MAX_NAME_LENGTH
    raise Ga4ConstraintError,
      "Param name #{name.inspect} exceeds GA4 max length of #{MAX_NAME_LENGTH} chars (got #{as_string.length})"
  end
end