Architectural Overview and System Requirements
The Presence API feature plugin (currently version 0.14.0) introduces real-time state tracking across WordPress environments. Designed for eventual core integration, the API provides visibility into active users across administrative dashboards, the block editor, and multisite networks. Implementing the feature plugin requires a minimum environment of WordPress 7.0 and PHP 7.4.
By default, presence tracking is active upon installation. System states are maintained in a dedicated custom table—presence—which tracks active sessions, client IDs, locations, and expiry timestamps. This custom table design avoids polluting standard WordPress options or meta tables, providing a dedicated layer for high-frequency heartbeat operations.
Post Lock Modernization and Object Cache Optimization
Historically, post locking in WordPress relied on updating post meta keys (specifically _edit_lock) within the wp_postmeta table. On sites configured with a persistent object cache (such as Redis or Memcached), updating post meta triggered a cache key invalidation for the affected post object. Periodic heartbeats from concurrent editors continuously invalidated post cache keys, degrading backend read performance.
In version 0.14.0, post locks have been entirely migrated from post meta into the primary presence database table (#551). Lock state refreshes now update dedicated rows within the presence table without modifying post meta objects. Consequently, persistent object caches retain valid post query caches, preventing unnecessary database round-trips during editing sessions.
// Example CLI command to manage recording globally without disrupting post locks
wp presence recording set off --network
Crucially, post locking functionality remains operational even if site-wide presence recording is explicitly disabled by an administrator (#644).
Multisite Presence Aggregation
For WordPress Multisite networks, tracking active users previously required querying individual sub-site tables or user states. The Presence API solves this scaling issue by utilizing a aggregated summary row mechanism (#332, #365).
Each sub-site continuously writes a single aggregated summary row into the main network table. When a Super Admin views the Network Admin dashboard, the system executes a single query against this consolidated table rather than iterating through database tables for every site in the network.
- Automatic Threshold: Network aggregation is enabled by default for networks where
wp_is_large_network()returnsfalse. - Programmatic Override: Developers can toggle network aggregation using the
wp_presence_network_aggregation_enabledfilter.
add_filter( 'wp_presence_network_aggregation_enabled', function( $enabled ) {
// Force aggregation on custom large network setups
return true;
} );Privacy Controls, Capabilities, and Data Management
Presence recording includes built-in privacy governance operating at both the network and individual site levels. Controls are exposed via administrative screens and command-line interfaces:
- Site Control: Configured via
Settings > General. - Network Control: Configured via
Network Admin > Settings. - Override Logic: If either the site-level or network-level setting is set to disabled, global recording is turned off. The network setting acts as an absolute master override (#429, #442).
- WP-CLI Management: Toggled using
wp presence recording set offorwp presence recording set off --network.
Data exposure is governed by the custom capability view_presence_location, which maps to list_users by default (#571). Users lacking this capability can see who is currently online in the admin bar, but cannot see where (which specific post or screen) those users are located. Users can always view their own presence information.
To support regulatory requirements like GDPR, presence data integrates directly with WordPress Core privacy tools, supporting automated data export and erasure routines (#449).
AI Agent Identification via REST and MCP
Automated AI agents executing content modifications over REST APIs or Model Context Protocol (MCP) endpoints do not initiate JavaScript Heartbeat pings. Without special handling, automated edits would occur without showing presence or locking indicators to human editors.
To resolve this, every write action executed by an AI agent creates a dedicated row in the post’s room within the presence table (#653). By default, this row automatically expires 75 seconds after the last save event (#697, #701).
Presence indicators display an explicit Agent badge in both the WordPress admin bar and the post list Editors column. Agent detection relies on pluggable checks:
// Programmatic identification of AI Agent user accounts
add_filter( 'wp_presence_is_agent_user', function( $is_agent, $user_id ) {
if ( get_user_meta( $user_id, 'is_bot_account', true ) ) {
return true;
}
return $is_agent;
}, 10, 2 );If the
Agent Usersplugin is active, the Presence API automatically querieswpai_is_agent_user(). If no plugin or filter responds, the user is rendered as a standard account.Client-Side Optimizations and Throttling
To reduce client-side overhead and server load during extended editing sessions, several performance optimizations were introduced in recent updates:
- Tab Federation: If a user has multiple browser tabs open to the same site, only one primary tab executes Heartbeat pings (#675). The active tab broadcasts incoming presence updates to background tabs.
- Idle Back-off: Background tabs stop transmitting presence requests, while idle active tabs automatically decrease ping frequencies (#300, #307).
- Database Read Throttling: Presence query results are cached in-memory per request until table modification events occur, reducing Heartbeat reads on screens like
users.phpfrom 6 queries down to 2 (#678). - High-DPI Support: Avatar rendering dynamically requests retina-resolution images (#481).
Developer APIs, Hooks, and Debugging Tools
Version 0.14.0 refactors dynamic properties and expands the internal PHP API. Static color values are no longer stored directly inside REST presence payload representations. Instead, color lookup is derived dynamically via wp_presence_get_user_color() based on the block editor's palette assignment (#707).
New Helper Functions
wp_presence_exchange(): Handles bidirectional presence payload exchanges during Heartbeat ticks (#546).wp_presence_leave(): Explicitly terminates a user's presence session within a designated room (#519).wp_presence_is_available(): Validates whether presence tracking is operational in the current context.
Database & Engine Compatibility
Presence queries filter directly by client ID prefixes within SQL statements (#530, #541), and write operations fully support SQLite installations (#623). For developers building real-time collaboration engines, such as the Gutenberg Sync Engines plugin, presence records integrate seamlessly (identified in presence tables via the gse- client prefix).
Admin Bar Debugger
An administrative debugging tool replaces the legacy dashboard widget (#652, #666). The debugger is strictly a development utility: it loads exclusively when WP_DEBUG is set to true and is omitted from standard WordPress.org production releases. Third-party plugins can register custom entries directly into the debugger toolbar to monitor real-time state changes.
Frequently asked questions
Why did the Presence API move post locks out of post meta?
Moving post locks to the custom presence table prevents post lock refreshes from continuously invalidating persistent object cache keys (like Redis or Memcached) for posts, significantly improving read performance on busy sites.
How are AI agents tracked if they do not run the JavaScript Heartbeat?
When an AI agent saves content via REST or MCP, a presence row is automatically written to the post's room with a default 75-second expiration timer, displaying an 'Agent' badge in the admin bar and Editors column.
Which capability controls who can see detailed user editing locations?
Location tracking visibility is controlled by the view_presence_location capability, which maps to list_users by default. Users without this capability can see who is online, but not their specific location.
Does disabling presence recording turn off post locks?
No. Post locking continues to function normally even if presence recording is switched off via site settings, network settings, or WP-CLI.
Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.