PhoenixKitWebAnalytics.Config (PhoenixKitWebAnalytics v0.5.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_detect_bots`	`true`	Also flag bots by behaviour — see `PhoenixKitWebAnalytics.BotSignals`
`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_track_interactions`	`true`	Record LiveView events (clicks, submits) as interactions
`web_analytics_ignore_events`	`validate`	LiveView event names never recorded as interactions
`web_analytics_event_params`	`tab, view, …`	Event param names whose short values are kept
`web_analytics_client_script`	`false`	Accept clicks / scroll / leave from the optional client script
`web_analytics_recording`	`false`	Record pointer movement, clicks, hovers and scrolling (session recordings)
`web_analytics_recording_sample`	`100`	Percent of visitors recorded while recording is on
`web_analytics_recording_retention_days`	`30`	Age at which recordings are deleted
`web_analytics_hash_secret`	generated	Secret mixed into the daily visitor hash

Summary

Types

collection_config()

Functions

beacon_enabled?()

Whether the beacon / pixel endpoints accept hits.

client_script?()

Whether the optional client script's hits (clicks, scroll, leave) are accepted.

collection_config()

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

default_event_params()

Default event param names whose values are kept.

default_exclusions()

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

default_ignore_events()

Default LiveView event names that are never recorded.

enabled?()

Whether tracking is switched on.

enabled_key()

Settings key for the module's master switch.

event_params()

LiveView event param names whose short values an interaction keeps.

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 the one that ended up stored (nil if it couldn't be written) — a rotation. The first salt is created through hash_salt/0 instead, under a lock, so concurrent first hits agree on it.

geo_resolver()

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

hash_salt()

The secret mixed into the daily visitor hash, or nil when it can't be read or created — in which case the hit is dropped rather than hashed with a guessable fallback.

ignored_event?(event)

Whether a LiveView event is left out of the interaction record — either interaction tracking is off, or the name is in the ignore list. A trailing * in the list matches a prefix, as with path exclusions.

module_key()

The module_key/0 these settings are attributed to.

recording_retention_days()

Days of session recordings to keep (30 by default).

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(),
  detect_bots?: boolean(),
  respect_dnt?: boolean(),
  beacon_enabled?: boolean(),
  exclusions: [String.t()],
  session_timeout_minutes: pos_integer(),
  track_interactions?: boolean(),
  client_script?: boolean(),
  recording?: boolean(),
  recording_sample: 1..100,
  ignore_events: [String.t()],
  event_params: [String.t()]
}

Functions

beacon_enabled?()

@spec beacon_enabled?() :: boolean()

Whether the beacon / pixel endpoints accept hits.

client_script?()

@spec client_script?() :: boolean()

Whether the optional client script's hits (clicks, scroll, leave) are accepted.

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_event_params()

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

Default event param names whose values are kept.

default_exclusions()

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

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

default_ignore_events()

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

Default LiveView event names that are never recorded.

enabled?()

@spec enabled?() :: boolean()

Whether tracking is switched on.

enabled_key()

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

Settings key for the module's master switch.

event_params()

@spec event_params() :: [String.t()]

LiveView event param names whose short values an interaction keeps.

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() | nil

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() | nil

The secret mixed into the daily visitor hash, or nil when it can't be read or created — in which case the hit is dropped rather than hashed with a guessable fallback.

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.

ignored_event?(event)

@spec ignored_event?(String.t()) :: boolean()

module_key()

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

The module_key/0 these settings are attributed to.

recording_retention_days()

@spec recording_retention_days() :: pos_integer()

Days of session recordings to keep (30 by default).

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.