Search documentation of phoenix_kit

# PhoenixKit.Dashboard.Presence (phoenix_kit v1.7.87)

Copy Markdown View Source

Presence tracking for dashboard tabs.

Tracks which users are viewing which dashboard tabs, enabling features like:

- "2 users viewing" indicators on tabs
- Real-time user count updates
- Activity heatmaps
- User awareness for collaborative features

## Integration with PhoenixKit Presence

This module integrates with PhoenixKit's existing presence system to provide dashboard-specific tracking while sharing the underlying infrastructure.

## Usage in LiveViews

    def mount(_params, _session, socket) do
      if connected?(socket) do
        # Track user on this tab
        PhoenixKit.Dashboard.Presence.track_tab(socket, :orders)

        # Subscribe to presence updates
        PhoenixKit.Dashboard.Presence.subscribe()
      end

      {:ok, assign(socket, tab_viewers: Presence.get_tab_viewers(:orders))}
    end

    def handle_info({:presence_diff, _diff}, socket) do
      {:noreply, assign(socket, tab_viewers: Presence.get_tab_viewers(:orders))}
    end

## Configuration

    config :phoenix_kit, :dashboard_presence,
      enabled: true,
      show_user_count: true,
      show_user_names: false,  # Privacy setting
      track_anonymous: false

## Summary

### Functions

broadcast_tab_count(tab_id)

Broadcasts a tab viewer count update.

clear_presence_module_cache()

Clears the cached presence module detection.

enabled?()

Checks if presence tracking is enabled.

get_all_tab_counts()

Gets viewer counts for all tabs at once.

get_tab_viewers(tab_id, opts \\ [])

Gets all users currently viewing a specific tab.

presence_topic()

Gets the main presence topic for all dashboard presence updates.

show_user_count?()

Checks if user counts should be shown.

show_user_names?()

Checks if user names/emails should be shown.

subscribe()

Subscribes to presence updates for all dashboard tabs.

subscribe_tab(tab_id)

Subscribes to presence updates for a specific tab.

tab_topic(tab_id)

Gets the presence topic for a specific tab.

track_anonymous?()

Checks if anonymous users should be tracked.

track_tab(socket, tab_id, opts \\ [])

Tracks a user's presence on a specific dashboard tab.

untrack_tab(socket, tab_id)

Untracks a user from a dashboard tab.

## Functions

# broadcast_tab_count(tab_id)

    @spec broadcast_tab_count(atom()) :: :ok

Broadcasts a tab viewer count update.

This is called automatically when presence changes, but can also be called manually to force a refresh.

# clear_presence_module_cache()

    @spec clear_presence_module_cache() :: :ok

Clears the cached presence module detection.

Call this after hot code reloading if the presence module configuration has changed. The next call to any presence function will re-detect.

# enabled?()

    @spec enabled?() :: boolean()

Checks if presence tracking is enabled.

# get_all_tab_counts()

    @spec get_all_tab_counts() :: map()

Gets viewer counts for all tabs at once.

Returns a map of tab_id => count.

## Examples

    Presence.get_all_tab_counts()
    # => %{orders: 3, printers: 1, settings: 0}

# get_tab_viewers(tab_id, opts \\ [])

    @spec get_tab_viewers(
      atom(),
      keyword()
    ) :: list() | integer()

Gets all users currently viewing a specific tab.

## Options

- `:format` - Output format: :full (default), :count, :emails, :ids

## Examples

    Presence.get_tab_viewers(:orders)
    # => [%{user_uuid: "019...", user_email: "user@example.com", online_at: ~U[...]}]

    Presence.get_tab_viewers(:orders, format: :count)
    # => 3

    Presence.get_tab_viewers(:orders, format: :emails)
    # => ["user@example.com", "admin@example.com"]

# presence_topic()

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

Gets the main presence topic for all dashboard presence updates.

# show_user_count?()

    @spec show_user_count?() :: boolean()

Checks if user counts should be shown.

# show_user_names?()

    @spec show_user_names?() :: boolean()

Checks if user names/emails should be shown.

# subscribe()

    @spec subscribe() :: :ok | {:error, term()}

Subscribes to presence updates for all dashboard tabs.

The subscriber will receive messages in the format:

- `{:presence_diff, %{joins: %{}, leaves: %{}}}` - When users join/leave
- `{:tab_viewers_updated, tab_id, count}` - Simplified count update

# subscribe_tab(tab_id)

    @spec subscribe_tab(atom()) :: :ok | {:error, term()}

Subscribes to presence updates for a specific tab.

# tab_topic(tab_id)

    @spec tab_topic(atom()) :: String.t()

Gets the presence topic for a specific tab.

# track_anonymous?()

    @spec track_anonymous?() :: boolean()

Checks if anonymous users should be tracked.

# track_tab(socket, tab_id, opts \\ [])

    @spec track_tab(Phoenix.LiveView.Socket.t(), atom(), keyword()) ::
      {:ok, String.t()} | {:error, term()}

Tracks a user's presence on a specific dashboard tab.

## Options

- `:meta` - Additional metadata to track with the presence (default: %{})
- `:tab_path` - The full path of the tab (used for analytics)

## Examples

    Presence.track_tab(socket, :orders)
    Presence.track_tab(socket, :printers, meta: %{printer_id: 123})

# untrack_tab(socket, tab_id)

    @spec untrack_tab(Phoenix.LiveView.Socket.t(), atom()) :: :ok

Untracks a user from a dashboard tab.