Skip to main content

Clients

The Clients page displays all browser clients and devices connected to GEM, including user agents, connection status, IP addresses, and session information.

Overview​

Client tracking provides:

  • Active Connections: Currently connected clients
  • Session History: Recent connection history
  • Device Information: Browser, OS, device type
  • User Association: Which user is logged in
  • Identify Feature: Flash screen to identify which physical device
  • Client Management: Disconnect or delete client records

Summary Statistics​

Cards showing aggregate metrics:

Total Clients: All client records (active and historical)

Connected Now: Currently connected browsers/apps

Online, Logged Out: Clients with a live connection but no signed-in session — a wall panel sitting on the login screen counts here. After an update or restart that ended sessions, this card is the list of panels that need to be logged back in (the tile highlights when the count is non-zero)

Authenticated: Clients with logged-in users

Active Last Hour: Clients seen within the past 60 minutes

Auto-Refresh: Updates every 30 seconds

Client List​

Table of all client records:

Columns:

  • Status: A status dot — green for online, gray for offline, amber for Online · logged out (the connection is live but no one is signed in, so the device is sitting on the login screen). The logged-out verdict comes from the server's own session state, not from anything the client reports
  • IP Address: Client IP address
  • Device & Browser: Parsed user agent with device icon
  • User: Logged-in username (if authenticated). The name is a link that opens the user account in a reference modal over this page — the list's filters, scroll position, and refresh cycle are kept. When the modal can't open, it falls back to the Users page filtered to that account
  • Page: The page the client is currently displaying (e.g. /av/kitchen), reported by the client whenever it navigates. A logged-out client can't report, so its row keeps the last page it showed while signed in — which is usually exactly what identifies the physical panel. Clients that haven't reloaded since this feature shipped show nothing here
  • Auth Method: How the session was authenticated — password or pin (sessions created before this was recorded show nothing and are password logins)
  • Last Seen: Last activity timestamp
  • Session Age: How long since the session's rolling activity window last slid forward. Activity extends a session, so for a client in regular use this stays small (the slide is persisted every few minutes) — it grows only while the session sits idle, and the session expires when it exceeds the account's Session Timeout
  • Push Notifications: Whether client has push notifications enabled
  • Default UI: The UI assigned to this client
  • AV Zone: The AV zone assigned to this client

This list is read-only, so nothing here can be edited in place — but its values can be copied: hover a cell for a copy icon, or focus it and press Ctrl+C. That is the quickest way to lift an IP address or a full user agent out for a ticket. See Zones — Copying Values.

Device Information Display​

User agents are parsed into a short device + browser label:

Examples:

iPhone 15.2 · Safari 15
macOS 12.1 · Chrome 96
Windows 10/11 · Edge 95
Android 12 · Firefox 94

Client Actions​

View Details​

Click the View icon on a row to open the client detail modal. The modal shows the full user agent, session age, token creation time, last-seen timestamp with relative age, the page the client is currently displaying (and since when), assigned default UI and AV zone, authentication method, push-notification status, and the underlying IP and client ID. Its Status line carries the same three states as the list — Online, Offline, or Online · logged out. The same modal opens from the client-ID links in Request History.

Auth method decides admin authority

A session whose auth method is pin never carries admin authority, whatever roles the user holds — it reaches its UIs and controls (including devices and macros flagged Elevated) but not admin-only functions, secure attribute values, generic writes, backups, or the /admin console. If a panel's admin access "stopped working", check this column before the user's roles: its denials appear in Request History as admin_only_pin_session. See Roles → Elevated.

Identify Client​

Click Identify button to flash the client's screen:

How It Works:

  1. Button clicked in admin interface
  2. Signal sent to specific client
  3. Client screen flashes or shows overlay
  4. Helps identify which physical device is which client

Use Cases:

  • Multiple tablets in same room
  • Unknown client connections
  • Verifying client after configuration change
  • Training users on which panel is which

Identify All Button: Flashes all connected clients simultaneously

Delete Client​

Remove client record from database:

When to Delete:

  • Old inactive client records
  • Test clients no longer used
  • Duplicate client entries

Confirmation: Shows client details before deletion

Impact:

  • Client record removed
  • If client reconnects, new record created
  • User can log in again

Connection Status​

Connection status is read from the server's live socket registry each time the list loads or refreshes — a client shows Online only while its WebSocket is actually connected. The same live state backs the Connected Now card and the client detail modal.

A client record can hold more than one live socket — two browser tabs on the same machine share one client id — and the session is torn down only when the last of them closes. That is what keeps a role or account change propagating to every open tab: revocation reaches sessions the server still considers connected, so a surviving tab cannot keep the permissions it was granted before the edit. A socket that presents a known client id but cannot prove it owns that session is given a fresh, unbound session of its own instead of adopting the existing one; it can still sign in normally, and the bound session it named is left untouched. Once that socket does sign in — or otherwise proves the session — it takes its place in the registry, so a client that signs back in after a sign-out and a reconnect is reachable by push and by the admin console again without waiting for another reconnect.

When a client record changes hands​

Signing in re-points the record at whoever just authenticated: on a shared wall panel, one person signs out and the next signs in on the same record. That is normal, and the panel keeps its Default UI, its AV Zone and its push registration across the switch — it is the same physical device either way.

What is not allowed is a sign-in claiming a record that is currently signed in as somebody else, when the sign-in did not come from the browser already holding it. The client id identifies a device but does not authenticate it — it travels in proxy and tunnel logs and is readable from the browser — so without this rule anyone holding any credential of their own could rotate a known client id's session and knock its owner offline at their next reconnect, inheriting that device's push registration in the process.

Such a sign-in is refused, and the server logs it with both user ids:

login refused, client id holds another live session: gem_client_… held by user 4 - claimed by user 7

The refusal is invisible to the person signing in. Their app takes a new client id of its own, reconnects and presents the same credential again, so they simply sign in — on a new record, leaving the existing one untouched. That is also why the rightful owner is never locked out of their own panel: if somebody else's session ever ends up on their record, their next sign-in gives them a fresh one rather than refusing them.

The practical signs are a new client record appearing for a device you already had one for, and that log line. A record whose owner has moved on can be deleted from this page once its Connected column reads offline. If the log line names a client id nobody should be signing in on, treat it as evidence the id is being reused somewhere it should not be.

Connected​

Green indicator:

  • Client actively connected via WebSocket
  • Receiving real-time updates
  • Can send commands

Disconnected​

Red/gray indicator:

  • Client not currently connected
  • Record exists (historical)
  • Last seen time shows last activity

Session Duration​

Calculated from the session's activity-window anchor (which slides forward with use — see Session Age above) to:

  • Current time (if connected)
  • Last seen time (if disconnected)

User Sessions​

Authenticated Clients​

Clients with logged-in users:

  • User column shows username
  • Associated with user account
  • Subject to user's role permissions

Unauthenticated Clients​

Clients connected but not logged in:

  • Limited or no access
  • May be on login screen
A client record starts at first sign-in

A record is created the first time a browser or panel completes a login, not when it connects. A device sitting on the login screen that has never signed in therefore has no row here at all, and a client whose session has since been deleted reappears the next time someone signs in on it.

This is why the list no longer fills with short-lived rows carrying no user: connecting is something anything on the network can do, so a row per connection was a table that grew without an account behind any of it. Rows with an empty User column are now sessions that signed in and were later signed out or deleted, which is the case worth looking at.

Auto-Refresh​

Client list refreshes automatically:

Interval: 30 seconds

Updates:

  • Connection status
  • Last seen timestamps
  • New clients added
  • Disconnected clients marked

Manual Refresh: Click refresh button anytime

Troubleshooting​

Unknown Clients​

Symptom: Client shown but unknown who/where

Solutions:

  1. Use Identify button to flash screen
  2. Review IP address (correlate to network DHCP)
  3. Check user agent for device hints
  4. Delete if unused/old record

Client Not Showing​

Check:

  1. Client actually connected (check on device)
  2. Page auto-refreshed (or manual refresh)
  3. Network connectivity
  4. Client not blocked by firewall

Identify Not Working​

Check:

  1. Client is connected (not disconnected)
  2. Browser supports the identify feature
  3. Client browser not in background/minimized
  4. JavaScript enabled on client

Too Many Old Clients​

Cleanup:

  1. Sort by last seen
  2. Identify old clients (months old)
  3. Delete individually or in batches
  4. Or use Data Retention settings for automatic cleanup (if applicable)

Security Considerations​

Monitoring for Intrusions​

Watch for:

  • Unknown IP addresses
  • Connections outside normal hours
  • Multiple failed authentication attempts
  • Suspicious user agents

Rogue Client Detection​

Indicators:

  • Client from unexpected IP range
  • User agent doesn't match expected devices
  • Connection during off-hours
  • Unauthenticated client persisting

Actions:

  1. Investigate IP address
  2. Review network logs
  3. Change passwords if compromised
  4. Block IP at firewall if malicious
  5. Enable 2FA for users