PhoenixKitWebAnalytics.Config (PhoenixKitWebAnalytics v0.2.0)

Settings-backed configuration for the Web Analytics module.

Everything an operator can change lives in the host's phoenix_kit_settings table under a web_analytics_ prefix, so it is editable from the admin Settings tab with no redeploy. This module is the only place that knows the key names and their defaults.

Hot path

collection_config/0 is called on every tracked request, so it reads through PhoenixKit.Settings.get_settings_cached/2 — one ETS multi-get, not a query per key — and every accessor degrades to its default (tracking off) if the settings table isn't reachable. Nothing here may raise: a broken settings read must cost the host a missing analytics row, never a failed page render.

Keys

Key	Default	What it does
`web_analytics_enabled`	`false`	Master switch (the module toggle)
`web_analytics_track_bots`	`false`	Store hits whose User-Agent looks automated
`web_analytics_respect_dnt`	`true`	Skip requests sending `DNT: 1`
`web_analytics_exclude_paths`	`/admin*` …	Newline/comma separated path patterns to ignore
`web_analytics_session_timeout_minutes`	`30`	Inactivity gap that ends a session
`web_analytics_retention_days`	`365`	Age at which raw events are rolled up and deleted
`web_analytics_beacon_enabled`	`false`	Accept hits from the JS beacon / pixel endpoints
`web_analytics_hash_salt`	generated	Secret mixed into the daily visitor hash

Summary

Types

collection_config()

Functions

beacon_enabled?()

Whether the beacon / pixel endpoints accept hits.

collection_config()

Every setting the collection path needs, in one cached read.

default_exclusions()

The default path exclusions, used when the setting was never written.

enabled?()

Whether tracking is switched on.

enabled_key()

Settings key for the module's master switch.

exclude_paths_raw()

Raw path-exclusion setting value, for the settings form.

excluded?(path, exclusions)

Whether path matches any exclusion pattern.

generate_salt()

Generates and persists a new visitor hash salt, returning it.

geo_resolver()

The geo resolver module, or nil when none is configured.

hash_salt()

The secret mixed into the daily visitor hash.

module_key()

The module_key/0 these settings are attributed to.

retention_days()

Days of raw events to keep. 0 disables pruning entirely (rollups are still written).

session_timeout_minutes()

Inactivity gap, in minutes, after which a new session starts.

setting_keys()

Settings keys owned by this module, for the admin settings form.

Types

collection_config()

@type collection_config() :: %{
  enabled?: boolean(),
  track_bots?: boolean(),
  respect_dnt?: boolean(),
  beacon_enabled?: boolean(),
  exclusions: [String.t()],
  session_timeout_minutes: pos_integer()
}

Functions

beacon_enabled?()

@spec beacon_enabled?() :: boolean()

Whether the beacon / pixel endpoints accept hits.

collection_config()

@spec collection_config() :: collection_config()

Every setting the collection path needs, in one cached read.

Returns defaults (with enabled?: false) if settings are unavailable, so a caller can treat the result as authoritative without a rescue of its own.

default_exclusions()

@spec default_exclusions() :: String.t()

The default path exclusions, used when the setting was never written.

enabled?()

@spec enabled?() :: boolean()

Whether tracking is switched on.

enabled_key()

@spec enabled_key() :: String.t()

Settings key for the module's master switch.

exclude_paths_raw()

@spec exclude_paths_raw() :: String.t()

Raw path-exclusion setting value, for the settings form.

excluded?(path, exclusions)

@spec excluded?(String.t(), [String.t()]) :: boolean()

Whether path matches any exclusion pattern.

A pattern is a literal path, optionally ending in * to match a prefix. Matching is case-sensitive and anchored at the start of the path.

iex> PhoenixKitWebAnalytics.Config.excluded?("/admin/users", ["/admin*"])
true

iex> PhoenixKitWebAnalytics.Config.excluded?("/blog", ["/admin*"])
false

generate_salt()

@spec generate_salt() :: String.t()

Generates and persists a new visitor hash salt, returning it.

Called on first use and from enable_system/0 so a fresh install has one before the first request arrives.

geo_resolver()

@spec geo_resolver() :: module() | nil

The geo resolver module, or nil when none is configured.

A resolver implements PhoenixKitWebAnalytics.Geo and turns an IP tuple into %{country_code: _, region: _, city: _}. There is no bundled implementation — no IP database ships with this package.

config :phoenix_kit_web_analytics, geo_resolver: MyApp.GeoIP

hash_salt()

@spec hash_salt() :: String.t()

The secret mixed into the daily visitor hash.

Generated and persisted on first use. Losing it is harmless — it only means visitor IDs computed before and after the change don't line up — but it must never be exposed to clients, since the hash could then be recomputed from a guessed IP + User-Agent pair.

module_key()

@spec module_key() :: String.t()

The module_key/0 these settings are attributed to.

retention_days()

@spec retention_days() :: non_neg_integer()

Days of raw events to keep. 0 disables pruning entirely (rollups are still written).

session_timeout_minutes()

@spec session_timeout_minutes() :: pos_integer()

Inactivity gap, in minutes, after which a new session starts.

setting_keys()

@spec setting_keys() :: %{required(atom()) => String.t()}

Settings keys owned by this module, for the admin settings form.