WordPress Online Status
The {CODICTS} Online Status plugin tracks and displays the online/offline status of registered users on your WordPress site. It uses a smart heartbeat system to detect active users and provides shortcodes, a REST API, and admin pages to display and query user presence in real time.
This plugin has no external theme or plugin dependencies — it works with any WordPress installation.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
Once activated, navigate to “Online Status” in the WordPress admin sidebar to view user activity and configure settings.
Key Features
| Feature | Description |
|---|---|
| Real-Time Tracking | Detects active users via the WordPress Heartbeat API — no custom polling needed. |
| Three Shortcodes | Display individual user status, online/offline user counts, and session logs. |
| AJAX Mode | Cache-friendly shortcode rendering that fetches fresh status after page load. |
| REST API | External heartbeat and status endpoints for mobile apps or third-party integrations. |
| Session Logging | Tracks login sessions with start time, last seen, and duration in a custom database table. |
| Cross-Tab Coordination | Only one browser tab per user sends heartbeat requests, reducing server load by 90%+ when users have multiple tabs open. |
| Admin Dashboard | User status list with search, sorting, and per-user session log drill-down. |
| Shortcode Builder | Interactive admin page that generates shortcodes with live preview. |
| Custom Endpoints | Track user presence across multiple platforms (website, mobile app, etc.) independently. |
| Automatic Log Cleanup | Configurable retention period for session log records. |
How It Works
The plugin determines whether a user is “online” based on when their last heartbeat was received. If the last heartbeat was within the past 15 minutes, the user is considered online. Otherwise, they’re offline.
| Status | Condition |
|---|---|
| Online | Last heartbeat within 15 minutes. |
| Offline | Last heartbeat older than 15 minutes. |
| Last Seen | Offline, but shows when the user was last active (optional). |
| Never Active | No heartbeat has ever been recorded for the user. |
The plugin tracks users through three complementary methods: the WordPress Heartbeat API (while a tab is open), page navigation (when the user moves between pages), and the REST API (for external platforms like mobile apps). All three methods share a single throttle — at most one database write per 5 minutes per user — keeping server load minimal.
Smart multi-tab handling: If a user has multiple browser tabs open, only one tab sends heartbeat data. The plugin automatically elects a “leader” tab and detects if it crashes or is closed, seamlessly promoting another tab. This prevents multiple tabs from multiplying server requests.
Admin Pages
The plugin adds three pages under the “Online Status” menu in the WordPress admin:
User Status Overview
The main page shows a list of all users who have heartbeat records, with their current online/offline status.
| Column | Description |
|---|---|
| User | Display name, linked to their WordPress profile. |
| Endpoint | Which platform the status is for (e.g., “Site”, “App”). |
| Activity | Green “Online” badge, “Last seen X ago”, or red “Offline”. |
| Action | “View Logs” link to see the user’s session history. |
You can search users by name or email, sort by activity, and configure items per page via Screen Options.
User Session Logs
Click “View Logs” for any user to see their session history — each session shows the start time, how long it lasted, and whether it’s still active.
Shortcode Builder
An interactive page that generates shortcode markup for you. Fill in the parameters and the shortcode updates in real time. Click “Copy” to copy it to your clipboard. See the Shortcodes section below for details.
Shortcodes
The plugin provides three shortcodes. You can build them manually or use the Shortcode Builder admin page.
1. Per-User Status
Displays the online/offline status of a specific user with a colored dot indicator.
[codicts-online-status user_id=”42″]
| Parameter | Default | Description |
|---|---|---|
user_id | Current author | The WordPress user ID to check. |
online_text | “Online” | Text shown when the user is online. |
offline_text | “Offline” | Text shown when the user is offline. |
use_last_seen | “false” | Set to "true" to show “Last seen X ago” instead of the offline text. |
last_seen_text | “Last seen %s ago” | Template for last seen text. %s is replaced with the time difference. |
never_active_text | “Never Active” | Text shown when the user has never been tracked. |
endpoint | “cdts_site” | Which endpoint to check. Supports comma-separated values (e.g., "cdts_site,app") — if the user is online on any listed endpoint, they show as online. |
ajax | “false” | Set to "true" for cache-friendly rendering (see AJAX Mode). |
loading_text | “Loading…” | Text shown while fetching status in AJAX mode. |
Examples:
[codicts-online-status user_id=”42″]
[codicts-online-status user_id=”42″ online_text=”Active Now” offline_text=”Away”]
[codicts-online-status user_id=”42″ use_last_seen=”true” last_seen_text=”Seen %s ago”]
[codicts-online-status user_id=”42″ endpoint=”cdts_site,app”]
[codicts-online-status user_id=”42″ ajax=”true” loading_text=”Checking…”]
2. Online/Offline User Count
Displays the number of online or offline users.
[codicts-online-status-count]
| Parameter | Default | Description |
|---|---|---|
status | “Online” | Which count to show: "Online" or "Offline". |
user_text | “Users” | Label for the count (e.g., “Members”, “People”). |
online_text | “Online” | Text appended for the online count. |
offline_text | “Offline” | Text appended for the offline count. |
remove_tags | “false” | Set to "true" to return just the number with no HTML wrapper. |
endpoint | “cdts_site” | Which endpoint to count users for. |
Examples:
[codicts-online-status-count]
[codicts-online-status-count status=”Offline” user_text=”Members”]
[codicts-online-status-count remove_tags=”true”]
Output: 5 Users Online (or just 5 with remove_tags="true").
3. User Session Logs
Displays a list of session log entries for a specific user.
[codicts-online-status-logs user_id=”42″]
| Parameter | Default | Description |
|---|---|---|
user_id | Current author | The WordPress user ID to show logs for. |
endpoint | “cdts_site” | Which endpoint to show logs for. |
limit | 10 | Maximum number of log entries to display. |
Each entry shows the session start date, how long it lasted, and an “Online” badge if the session is still active.
AJAX Mode (Cache-Friendly)
If your site uses page caching (via a CDN or caching plugin), the standard shortcode will show stale status data from the cached page. AJAX mode solves this by loading a placeholder first, then fetching fresh status data via JavaScript after the page loads.
To enable AJAX mode, add ajax="true" to the per-user status shortcode:
[codicts-online-status user_id=”42″ ajax=”true” loading_text=”Checking…”]
While the status is being fetched, users see the loading text with a pulsing gray dot. Once the data arrives, the actual status replaces the placeholder.
Tip: If you have multiple shortcodes on the same page for the same user, the plugin automatically groups them into a single request to minimize server calls.
Settings
Navigate to Online Status → Settings to configure the plugin.
Log Retention
| Setting | Default | Description |
|---|---|---|
| Logs Cache (in days) | 30 | How many days to keep session log records. A daily cleanup job automatically deletes older records while preserving the most recent session per user. |
Custom Endpoints
By default, the plugin tracks user presence on the website (endpoint: cdts_site). If you also want to track presence on other platforms — such as a mobile app — you can add custom endpoints.
1. Enable the “Enable Custom Heartbeat Endpoints” toggle.
2. Click “Add Endpoint” and enter a name (e.g., app, mobile).
3. Click “Save Settings”.
Custom endpoints can then be:
| Action | How |
|---|---|
| Updated | Via the REST API POST /heartbeat with the endpoint name. |
| Queried | Via the REST API GET /status or in shortcodes using the endpoint parameter. |
| Combined | Pass comma-separated endpoints: endpoint="cdts_site,app" — if the user is online on any endpoint, they show as online. |
REST API
The plugin provides two REST API endpoints for integrating with mobile apps or external systems. Both require authentication via WordPress Application Passwords with an administrator account.
The settings page includes a built-in API reference with full documentation and sample cURL commands.
POST /heartbeat — Update User Status
POST /wp-json/codicts-online-status/v1/heartbeat| Parameter | Required | Description |
|---|---|---|
user_id | Yes | The WordPress user ID to update. |
endpoint | Yes | A registered custom endpoint name (e.g., app). |
Example:
Returns {"status": true} on success, or {"status": true, "throttled": true} if the user was already updated within the last 5 minutes.
GET /status — Check User Status
GET /wp-json/codicts-online-status/v1/status?user_id=42&endpoint=cdts_site| Parameter | Required | Description |
|---|---|---|
user_id | Yes | The WordPress user ID to check. |
endpoint | No | Endpoint to check (default: cdts_site). Supports comma-separated values. |
Returns:
{
"is_online": true,
"last_seen": "3 minutes",
"is_never_seen": false
}Session Logging
The plugin automatically tracks user sessions in a custom database table. A “session” begins when a user’s heartbeat is first recorded (or when they return after being offline for more than 15 minutes) and continues as long as heartbeats keep arriving.
Each session records the start time, the last seen time, and whether the session has ended. When a user goes offline and comes back, the old session is closed and a new one begins.
Session logs are visible in the admin User Logs view and via the [codicts-online-status-logs] shortcode.
Log Cleanup
A daily cleanup job automatically removes session records older than the configured retention period (default: 30 days). The most recent session per user is always preserved, even if it’s older than the retention period.
Troubleshooting
Users Not Showing as Online
| Cause | Solution |
|---|---|
| User not logged in | Only logged-in users are tracked on the website. |
| WordPress Heartbeat disabled | Some performance or security plugins disable the WordPress Heartbeat API. Ensure it’s enabled on frontend pages. |
| Page caching showing stale data | Use ajax="true" on your shortcodes for cache-friendly rendering. |
| Wrong user ID | Verify the user_id in your shortcode matches the WordPress user ID. |
| Custom endpoint not registered | If using the endpoint parameter, ensure the endpoint is added in Settings and the custom endpoints toggle is enabled. |
“Never Active” Showing for a User
This means no heartbeat has ever been recorded for the user. They may have registered but not visited the site since the plugin was installed. Once they visit while logged in, their status will update.
Status Stuck on “Online” After User Leaves
The 15-minute timeout is by design — a user remains “online” for up to 15 minutes after their last activity to prevent flickering between online and offline during normal browsing. After 15 minutes without activity, their status changes to offline.
Shortcode Not Displaying Correctly
| Cause | Solution |
|---|---|
| Misspelled shortcode | Ensure the shortcode is exactly [codicts-online-status] with hyphens. |
| Invalid user ID | The user_id must be a valid WordPress user ID number. |
| AJAX mode JavaScript error | Check the browser console for errors. Ensure jQuery is loaded on the page. |
REST API Returns 403 Forbidden
The API requires an administrator account authenticated via WordPress Application Passwords. Verify the username and Application Password are correct, that the user has administrator privileges, and that the REST API isn’t blocked by a security plugin.
Session Logs Not Appearing
The session logging database table is created automatically on activation. If it’s missing, try deactivating and reactivating the plugin. Also check that the log retention setting isn’t set too low (e.g., 1 day), which could cause logs to be cleaned up before you see them.
High Server Load
The plugin is optimized to write to the database at most once per 5 minutes per user, regardless of how many tabs are open or how often pages are loaded. If you’re experiencing high load, verify you’re running version 4.0.0 or later, which replaced custom AJAX polling with the WordPress Heartbeat API and added cross-tab coordination.
For further support, visit codicts.com or contact us at support@codicts.com.