PhoenixKitWebAnalytics.Alerts (PhoenixKitWebAnalytics v0.5.0)

Copy Markdown View Source

Tells the site's staff when something happens on the site — a visitor arriving, someone signing up, an event you care about — through PhoenixKit's notification system, so it reaches the in-app inbox, email, or Telegram with no per-project code.

What can alert

Three notification sub-types under Website activity (notification_types/0), each switchable per person on the Notifications settings page, per channel, with core's aggregation (immediate / hourly / daily digest):

  • New visitors — the first page view of a new session. Off by default (web_analytics_alert_visitors), and narrowed by the filters below.
  • New sign-ups — an account was created, by any registration path (password, magic link, OAuth, admin). On by default (web_analytics_alert_signups).
  • Tracked events — a custom event or LiveView interaction whose name is listed in web_analytics_alert_events (e.g. order.placed, contact).

Keeping visitor alerts useful

A notification per visitor is a flood on any site with real traffic, so the visitor alert has filters, all in the module's Settings page:

  • channels — only visitors arriving from these channels (organic, social, referral, email, paid, none for direct);
  • landing pages — only sessions that start on a matching path (same * prefix patterns as path exclusions);
  • skip signed-in users — on by default; your own users browsing are not news;
  • hourly cap — at most N visitor alerts per hour (default 20); the next alert after a quiet spell says how many were held back.

Beyond that, a person can pick an hourly or daily digest for the type in their own notification settings, which turns the stream into one summary.

Who receives them

Everyone who can open Web Analytics: Owners, and every active user whose role grants the web_analytics permission (or the * wildcard). The list is cached for five minutes, so a revoked permission or a deactivated account can keep receiving alerts for up to five minutes.

Delivery

Each alert is one PhoenixKit.Activity entry per recipient (the recipient as target_uuid), which is what makes core route it and count it in digests. Alert text never includes an email address or anything a visitor typed.

Summary

Types

config()

Functions

channels()

The channel values the visitor filter understands.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

config()

The current alert settings, with defaults.

event_recorded(event, new_session?)

Called by the collector after every stored hit, in the collector's own (background) process. Decides whether the hit is alert-worthy and sends. Never raises.

notification_types()

The notification type this module registers with core — returned from PhoenixKitWebAnalytics.notification_types/0.

recipients()

Everyone who receives the alerts: Owners plus active holders of the web_analytics (or *) permission. Cached for five minutes.

setting_keys()

Settings keys owned by the alerts, for the settings form.

user_registered(user)

Sends the sign-up alert for a newly created user. Never raises.

visitor_alert?(event, config)

Whether a visitor's first page view passes the visitor-alert filters. Public so the settings page and tests can explain a decision.

Types

config()

@type config() :: %{
  visitors?: boolean(),
  signups?: boolean(),
  channels: [String.t()],
  paths: [String.t()],
  skip_users?: boolean(),
  max_per_hour: non_neg_integer(),
  events: [String.t()]
}

Functions

channels()

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

The channel values the visitor filter understands.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

config()

@spec config() :: config()

The current alert settings, with defaults.

event_recorded(event, new_session?)

@spec event_recorded(PhoenixKitWebAnalytics.Schemas.Event.t(), boolean()) :: :ok

Called by the collector after every stored hit, in the collector's own (background) process. Decides whether the hit is alert-worthy and sends. Never raises.

notification_types()

@spec notification_types() :: [map()]

The notification type this module registers with core — returned from PhoenixKitWebAnalytics.notification_types/0.

recipients()

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

Everyone who receives the alerts: Owners plus active holders of the web_analytics (or *) permission. Cached for five minutes.

setting_keys()

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

Settings keys owned by the alerts, for the settings form.

user_registered(user)

@spec user_registered(map()) :: :ok

Sends the sign-up alert for a newly created user. Never raises.

visitor_alert?(event, config)

@spec visitor_alert?(PhoenixKitWebAnalytics.Schemas.Event.t(), config()) :: boolean()

Whether a visitor's first page view passes the visitor-alert filters. Public so the settings page and tests can explain a decision.