Class: TrackRelay::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/track_relay/configuration.rb

Overview

Process-wide configuration for track_relay.

Holds every Phase-01 knob: the subscriber list, defaults for untyped-event handling, and the test-mode synchronous override. The host application configures it via configure; the rest of the gem reads it via config.

Examples:

Host-app initializer

TrackRelay.configure do |c|
  c.subscribe(MyAnalyticsSubscriber.new)
  c.untyped_events_allowed = false
  c.untyped_log_path = Rails.root.join("log/untyped_events.log")
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



93
94
95
 
# File 'lib/track_relay/configuration.rb', line 93

def initialize
  reset!
end

Instance Attribute Details

#client_id_resolvers ⇒ Object

Ordered chain of #call(controller:, **)-callables consulted by TrackRelay::ControllerTracking#_resolve_client_id to populate Current.client_id. First non-nil result wins. Defaults to [ClientId::Ga.new, ClientId::AhoyVisitor.new, ClientId::Session.new] (Plan 02-02 / REQ-26).



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#force_synchronous ⇒ Object

When true, subscribers run inline regardless of their async preference. Used by test_mode! (Plan 07) and integration tests.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#ga4_api_secret ⇒ Object

GA4 Measurement Protocol api_secret query parameter, scoped per data stream. Read at delivery time. Defaults to nil; same warn-and-skip behavior as #ga4_measurement_id when missing. Treat as a credential — never commit to source.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#ga4_enrich_page_context ⇒ Object

When true, the GA4 subscriber captures page context from the current request at notification time and merges it into the delivered event's params: page_location (request URL), page_referrer (when a referer exists), and — when the gtag session cookie _ga_<stream> is parseable — session_id plus a nominal engagement_time_msec. Without these GA4 files server-side events under a blank page path. Defaults to false.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#ga4_measurement_id ⇒ Object

GA4 Measurement Protocol measurement_id query parameter (G-XXXXXXXXXX). Read at delivery time so credentials lambdas / late-bound configs work. Defaults to nil; when nil at delivery time the GA4 subscriber emits a Rails.logger.warn and skips the POST without raising.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#ga4_require_browser_client_id ⇒ Object

When true, the GA4 subscriber delivers ONLY when the current request carries a genuine _ga cookie (set by gtag JS, which bots don't execute). No cookie — or a malformed one — means no DeliveryJob is enqueued at all; the random client_id fallback never fires. The cookie-derived client_id is merged into the delivered payload's context. Defaults to false (deliver everything, as before).



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#ga4_use_eu_endpoint ⇒ Object

When true, the GA4 subscriber posts to https://region1.google-analytics.com/mp/collect instead of the global endpoint. Defaults to false.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#raise_on_validation_error ⇒ Object

Whether catalog/payload validation errors raise (dev/test) or are merely logged (prod). Defaults to true in dev/test.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#subscribers ⇒ Array (readonly)

Returns registered subscriber instances, in insertion order.

Returns:

  • (Array) —

    registered subscriber instances, in insertion order



91
92
93
 
# File 'lib/track_relay/configuration.rb', line 91

def subscribers
  @subscribers
end

#swallow_subscriber_errors ⇒ Object

Whether subscriber exceptions are caught and logged instead of re-raised. Defaults to true in production, false elsewhere.



77
78
79
 
# File 'lib/track_relay/configuration.rb', line 77

def swallow_subscriber_errors
  @swallow_subscriber_errors
end

#track_gate ⇒ Object

Optional callable evaluated once per TrackRelay.track call, BEFORE the event notification fans out to any subscriber. Receives payload: (the built EventPayload) and request: (Current.request, possibly nil) keywords; a falsy return drops the event for every subscriber. nil (the default) disables the gate entirely — current behavior.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#untyped_events_allowed ⇒ Object

Whether TrackRelay.track accepts events not in the catalog.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

#untyped_log_path ⇒ Object

Optional path for logging untyped (non-catalog) events. nil disables the untyped log.



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/track_relay/configuration.rb', line 77

attr_accessor :swallow_subscriber_errors,
:untyped_log_path,
:untyped_events_allowed,
:force_synchronous,
:raise_on_validation_error,
:client_id_resolvers,
:ga4_measurement_id,
:ga4_api_secret,
:ga4_use_eu_endpoint,
:ga4_require_browser_client_id,
:ga4_enrich_page_context,
:track_gate

Instance Method Details

#replace_subscribers(list) ⇒ Array

Atomically replace the subscriber list and return the previous one. Plan 07's TrackRelay.test_mode! uses this to swap in a capturing subscriber for the duration of a test block and then restore the original list.

Parameters:

  • list (Array, nil) —

    new subscribers (nil is coerced to [])

Returns:

  • (Array) —

    the previous subscriber list (caller's snapshot)



135
136
137
138
139
 
# File 'lib/track_relay/configuration.rb', line 135

def replace_subscribers(list)
  previous = @subscribers
  @subscribers = Array(list)
  previous
end

#reset! ⇒ void

This method returns an undefined value.

Restore every setting to its environment-aware default and clear the subscriber list. Used by tests and by TrackRelay.reset_config!.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/track_relay/configuration.rb', line 101

def reset!
  @subscribers = []
  @swallow_subscriber_errors = production_env?
  @untyped_log_path = nil
  @untyped_events_allowed = true
  @force_synchronous = false
  @raise_on_validation_error = development_or_test_env?
  @client_id_resolvers = default_client_id_resolvers
  @ga4_measurement_id = nil
  @ga4_api_secret = nil
  @ga4_use_eu_endpoint = false
  @ga4_require_browser_client_id = false
  @ga4_enrich_page_context = false
  @track_gate = nil
end

#subscribe(subscriber) ⇒ Object

Append a subscriber to the registry.

Parameters:

  • subscriber (#call, Object) —

    any object conforming to the subscriber protocol (Plan 05 defines the contract).

Returns:

  • (Object) —

    the subscriber, so the call is chainable / usable as sub = config.subscribe(MySubscriber.new).



123
124
125
126
 
# File 'lib/track_relay/configuration.rb', line 123

def subscribe(subscriber)
  @subscribers << subscriber
  subscriber
end