PhoenixKit.Admin.Presence (phoenix_kit v2.37.1)

Phoenix.Presence implementation for tracking anonymous and authenticated sessions.

This module provides real-time tracking of:

Anonymous visitors (WebSocket connections without user_uuid)
Authenticated users (with user_uuid)
Session details like IP, User-Agent, current page, connection time

Usage

Track anonymous session:

PhoenixKit.Admin.Presence.track_anonymous(session_id, %{
  connected_at: DateTime.utc_now(),
  ip_address: get_connect_info(socket, :peer_data).address,
  user_agent: get_connect_info(socket, :user_agent),
  current_page: socket.assigns.current_path
})

Track authenticated session:

PhoenixKit.Admin.Presence.track_user(user, %{
  connected_at: DateTime.utc_now(),
  session_id: session_id,
  ip_address: get_connect_info(socket, :peer_data).address
})

track_user/2 is idempotent by (user.uuid, metadata.session_id) — tracking the same user/session pair again (a second open tab, another LiveView mounted under the same login) merges into the existing presence row instead of creating a duplicate. See PhoenixKit.Admin.SimplePresence for the multi-tab monitor-refcounting this relies on.

Events Generated

{:anonymous_session_connected, session_id, session_info}
{:anonymous_session_disconnected, session_id}
{:user_session_connected, user_uuid, session_info}
{:user_session_disconnected, user_uuid, session_id}
{:presence_stats_updated, stats}

Summary

Functions

child_spec(opts)

fetch(topic, presences)

Callback implementation for Phoenix.Presence.fetch/2.

fetchers_pids()

get_by_key(topic, key)

Callback implementation for Phoenix.Presence.get_by_key/2.

get_presence_stats()

Gets presence statistics.

get_topic()

Gets the presence topic name.

list(topic)

Callback implementation for Phoenix.Presence.list/1.

list_active_sessions()

Gets all currently active sessions (anonymous + authenticated).

list_anonymous_sessions()

Gets all anonymous sessions currently tracked.

list_authenticated_sessions()

Gets all authenticated user sessions currently tracked.

start_link(opts \\ [])

Starts the Presence process.

subscribe()

Subscribes to presence events for real-time updates.

track(socket, key, meta)

Callback implementation for Phoenix.Presence.track/3.

track(pid, topic, key, meta)

Callback implementation for Phoenix.Presence.track/4.

track_anonymous(session_id, metadata \\ %{})

Tracks an anonymous session in Presence.

track_user(user, metadata \\ %{})

Tracks an authenticated user session in Presence.

untrack(socket, key)

Callback implementation for Phoenix.Presence.untrack/2.

untrack(pid, topic, key)

Callback implementation for Phoenix.Presence.untrack/3.

update(socket, key, meta)

Callback implementation for Phoenix.Presence.update/3.

update(pid, topic, key, meta)

Callback implementation for Phoenix.Presence.update/4.

update_current_page(user_uuid, session_id, path)

Updates the :current_page an authenticated user's tracked session reports.

update_metadata(key, metadata_updates)

Updates metadata for an existing presence.

user_key(user_uuid, session_id)

Builds the presence key for a user's session — see SimplePresence.user_key/2.