Class: Omnitrack::Configuration

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

Overview

Central configuration object. Use Omnitrack.configure { |c| … } in an initializer.

Constant Summary collapse

VALID_MODES = 
%i[auto frontend backend hybrid].freeze
VALID_LOG_LVLS = 
%i[debug info warn error none].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/omnitrack/configuration.rb', line 54

def initialize
  @mode         = :auto
  @adapters     = {}
  @auto_capture = true
  @log_level    = :info
  @log_file     = nil   # resolved lazily against Rails.root
  @async        = false
  @queue_name   = :omnitrack
  @timeout      = 5
  @max_retries  = 3
  @retry_delay  = 1
  @on_error     = nil
  @admin_username = ENV.fetch("OMNITRACK_ADMIN_USERNAME", "admin")
  @admin_password = ENV.fetch("OMNITRACK_ADMIN_PASSWORD", "change-me")
  @dashboard_enabled = true
  @dashboard_per_page = 25
  @dashboard_mount_path = "/omnitrack"
end

Instance Attribute Details

#adapters ⇒ Object

Hash keyed by adapter symbol. Each value is a sub-hash of adapter options. Example:

{ google_ads: { enabled: true, customer_id: "123" },
  meta:        { enabled: true, pixel_id: "456" } }



19
20
21
 
# File 'lib/omnitrack/configuration.rb', line 19

def adapters
  @adapters
end

#admin_password ⇒ Object

Admin dashboard authentication (used by Omnitrack::Engine)



49
50
51
 
# File 'lib/omnitrack/configuration.rb', line 49

def admin_password
  @admin_password
end

#admin_username ⇒ Object

Admin dashboard authentication (used by Omnitrack::Engine)



49
50
51
 
# File 'lib/omnitrack/configuration.rb', line 49

def admin_username
  @admin_username
end

#async ⇒ Object

When true, dispatch tracking calls through ActiveJob (non-blocking)



31
32
33
 
# File 'lib/omnitrack/configuration.rb', line 31

def async
  @async
end

#auto_capture ⇒ Object

Automatically capture gclid / fbclid / ttclid from incoming requests



22
23
24
 
# File 'lib/omnitrack/configuration.rb', line 22

def auto_capture
  @auto_capture
end

#dashboard_enabled ⇒ Object

Admin dashboard behavior



52
53
54
 
# File 'lib/omnitrack/configuration.rb', line 52

def dashboard_enabled
  @dashboard_enabled
end

#dashboard_mount_path ⇒ Object

Admin dashboard behavior



52
53
54
 
# File 'lib/omnitrack/configuration.rb', line 52

def dashboard_mount_path
  @dashboard_mount_path
end

#dashboard_per_page ⇒ Object

Admin dashboard behavior



52
53
54
 
# File 'lib/omnitrack/configuration.rb', line 52

def dashboard_per_page
  @dashboard_per_page
end

#log_file ⇒ Object

Path to dedicated log file. Defaults to Rails.root/log/omnitrack.log



28
29
30
 
# File 'lib/omnitrack/configuration.rb', line 28

def log_file
  @log_file
end

#log_level ⇒ Object

:debug | :info | :warn | :error | :none



25
26
27
 
# File 'lib/omnitrack/configuration.rb', line 25

def log_level
  @log_level
end

#max_retries ⇒ Object

Max retry attempts for failed adapter calls



40
41
42
 
# File 'lib/omnitrack/configuration.rb', line 40

def max_retries
  @max_retries
end

#mode ⇒ Object

:auto — gem detects API-only vs full-stack at runtime :frontend — always inject JS helpers / use cookies :backend — server-side only; no JS :hybrid — both simultaneously



13
14
15
 
# File 'lib/omnitrack/configuration.rb', line 13

def mode
  @mode
end

#on_error ⇒ Object

Hook: called with (event_name, adapter_name, error) on adapter failure



46
47
48
 
# File 'lib/omnitrack/configuration.rb', line 46

def on_error
  @on_error
end

#queue_name ⇒ Object

Queue name used for ActiveJob tracking jobs



34
35
36
 
# File 'lib/omnitrack/configuration.rb', line 34

def queue_name
  @queue_name
end

#retry_delay ⇒ Object

Retry delay base in seconds (exponential back-off: delay * 2^attempt)



43
44
45
 
# File 'lib/omnitrack/configuration.rb', line 43

def retry_delay
  @retry_delay
end

#timeout ⇒ Object

HTTP timeout (seconds) for outbound adapter API calls



37
38
39
 
# File 'lib/omnitrack/configuration.rb', line 37

def timeout
  @timeout
end

Instance Method Details

#adapter_config(name) ⇒ Object

Returns the hash config for a specific adapter (or {})



110
111
112
 
# File 'lib/omnitrack/configuration.rb', line 110

def adapter_config(name)
  @adapters.fetch(name.to_sym, {})
end

#adapter_enabled?(name) ⇒ Boolean

True when the given adapter is enabled in config

Returns:

  • (Boolean) 


115
116
117
118
 
# File 'lib/omnitrack/configuration.rb', line 115

def adapter_enabled?(name)
  cfg = adapter_config(name)
  cfg.fetch(:enabled, false)
end

#effective_mode ⇒ Object

Effective Rails mode — resolves :auto at runtime



121
122
123
124
125
126
127
128
129
 
# File 'lib/omnitrack/configuration.rb', line 121

def effective_mode
  return @mode unless @mode == :auto

  if defined?(Rails) && Rails.application
    Rails.application.config.api_only ? :backend : :frontend
  else
    :backend
  end
end

#resolved_log_file ⇒ Object

Returns the resolved log file path (String)



99
100
101
102
103
104
105
106
107
 
# File 'lib/omnitrack/configuration.rb', line 99

def resolved_log_file
  return @log_file.to_s if @log_file

  if defined?(Rails) && Rails.root
    Rails.root.join("log", "omnitrack.log").to_s
  else
    "log/omnitrack.log"
  end
end

#validate! ⇒ Object 



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/omnitrack/configuration.rb', line 73

def validate!
  unless VALID_MODES.include?(@mode)
    raise Omnitrack::ConfigurationError,
          "Invalid mode: #{@mode.inspect}. Must be one of #{VALID_MODES}"
  end

  unless VALID_LOG_LVLS.include?(@log_level)
    raise Omnitrack::ConfigurationError,
          "Invalid log_level: #{@log_level.inspect}. Must be one of #{VALID_LOG_LVLS}"
  end

  unless @dashboard_per_page.to_i.positive?
    raise Omnitrack::ConfigurationError,
          "dashboard_per_page must be a positive integer"
  end

  mount_path = @dashboard_mount_path.to_s
  unless mount_path.start_with?("/") && mount_path.length > 1
    raise Omnitrack::ConfigurationError,
          "dashboard_mount_path must start with '/' (example: /omnitrack)"
  end

  true
end