Reference
JS API: window.WPS
The plugin exposes window.WPS on all pages where the client script is loaded.
If you are building a WordPress block or script with a build tool, add
'wpsignal' as a dependency in your
wp_enqueue_script call to ensure WPS loads first.
Quick example
// Listen for a specific event
document.addEventListener('wpsignal:post.updated', (e) => {
console.log(e.detail.data.post_title);
});
// OR use the WPS API directly
const unsub = WPS.on('post.updated', (data, channel) => {
console.log('Post updated on', channel, data);
});
// Unsubscribe later
unsub();WPS.subscribe( channels )
Subscribe to additional channels on the shared connection.
| Parameter | Type |
|---|---|
| channels | string[] |
WPS.unsubscribe( channels )
Unsubscribe from channels.
| Parameter | Type |
|---|---|
| channels | string[] |
WPS.publish( channel, event, data? )
Publish a JSON message through the WebSocket. No-ops on SSE (one-way transport).
| Parameter | Type |
|---|---|
| channel | string |
| event | string |
| data? | Record< string, unknown > |
WPS.publishBinary( channel, data )
Send a raw binary frame to the server over the WebSocket. Frame format: 2-byte BE channel name length + channel bytes + payload. No-ops on SSE (one-way transport) or when not connected.
| Parameter | Type |
|---|---|
| channel | string |
| data | Uint8Array |
WPS.setPresence( channel, state )
Enter or update connection-scoped presence on a channel. The relay drops the membership the instant this socket closes, and the client re-sends it on reconnect; pass null to leave, which is announced at once. Subscribers of the channel receive `wps.presence` join/leave/sync events (`channel` is the site-relative name, `woo:carts:live`). Requires WebSocket; no-op on SSE.
| Parameter | Type |
|---|---|
| channel | string |
| state | Record< string, unknown > | null |
WPS.on( event, handler )
() => void
Register a handler for a specific event name. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| event | string |
| handler | WPSEventHandler |
WPS.onMessage( handler )
() => void
Register a catch-all handler for incoming JSON messages. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | WPSMessageHandler |
WPS.onBinaryMessage( handler )
() => void
Register a handler for incoming binary frames. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | WPSBinaryHandler |
WPS.connected
readonly propertyboolean
Whether the connection is currently open.
WPS.transport
readonly propertyWPSTransportName | null
Current transport layer, or null while still connecting.
WPS.status
readonly propertyWPSStatus
Current transport state and capabilities.
WPS.onConnectionChange( handler )
() => void
Register a callback for connection state changes. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | ( connected: boolean ) => void |
WPS.onStateChange( handler )
() => void
Register a callback receiving the full connection state (error, retry countdown, failure count). Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | ( state: WPSConnectionState ) => void |
WPS.state
readonly propertyWPSConnectionState
The current connection state, as delivered to onStateChange.
WPS.uuid( )
string
A version-4 UUID. Works on plain HTTP pages too, where `crypto.randomUUID` does not exist (it needs a secure context); use it instead of calling `crypto.randomUUID()` directly. Needs no connection.
WPS.visitorId( )
string
This browser's stable id, kept in localStorage and shared by every tab and every extension on the site, for counting people rather than sockets (pass it in presence state). It names a browser, not a person; when storage is blocked it lasts for the page load only.
WPS.onChannel( channel, expected )
boolean
Whether an event's `channel` is the `expected` one, given by its site-relative name (`woo:stock`); the qualified `site:{id}:woo:stock` matches too. Any tokened browser may publish on a public channel, so check this in a handler before trusting the event's data.
| Parameter | Type |
|---|---|
| channel | string |
| expected | string |
Handler types
These types are used as parameters in the methods above.
WPSEventHandler
Used in WPS.on()
type WPSEventHandler = (
data: Record<string, unknown>,
channel: string
) => void;WPSMessageHandler
Used in WPS.onMessage()
type WPSMessageHandler = (
event: string,
data: Record<string, unknown>,
channel: string
) => void;WPSBinaryHandler
Used in WPS.onBinaryMessage(). For Yjs and other binary protocols.
type WPSBinaryHandler = (
channel: string,
data: Uint8Array
) => void;DOM CustomEvents
For every received message the client also dispatches a
CustomEvent on
document.
The event name is wpsignal:{event}.
Use these when you prefer the standard DOM event model.
document.addEventListener('wpsignal:post.updated', (e) => {
// e.detail = { event: 'post.updated', data: { ... }, channel: '...' }
console.log(e.detail.data);
});