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.



66
67
68
 
# File 'lib/track_relay/configuration.rb', line 66

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).



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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

#force_synchronous ⇒ Object

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



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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_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.



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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_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.



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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_use_eu_endpoint ⇒ Object

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



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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

#raise_on_validation_error ⇒ Object

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



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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

#subscribers ⇒ Array (readonly)

Returns registered subscriber instances, in insertion order.

Returns:

  • (Array) —

    registered subscriber instances, in insertion order



64
65
66
 
# File 'lib/track_relay/configuration.rb', line 64

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.



53
54
55
 
# File 'lib/track_relay/configuration.rb', line 53

def swallow_subscriber_errors
  @swallow_subscriber_errors
end

#untyped_events_allowed ⇒ Object

Whether TrackRelay.track accepts events not in the catalog.



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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

#untyped_log_path ⇒ Object

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



53
54
55
56
57
58
59
60
61
 
# File 'lib/track_relay/configuration.rb', line 53

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

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)



105
106
107
108
109
 
# File 'lib/track_relay/configuration.rb', line 105

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!.



74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/track_relay/configuration.rb', line 74

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
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)`.



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

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