Skip to main content
Markdown

Getting started

The WordPlus realtime SDK gives any WordPress plugin, theme or custom code realtime features on a site with a WordPlus Cloud subscription:

  • Channels: events from your server to browsers, and between browsers. See channels, presence, publishing and client events.
  • Calls between two people: they ring in the browser, run directly between the two browsers, and fall back to TURN, then to a media server, when the network needs it. See calls.
  • Group calls: a room on WordPlus Cloud's media servers. See group calls.
  • A drop-in call screen: a call button, a ring and a call window, with no JavaScript to write. See the call screen.
  • Encryption and WordPress's own users: what you send is sealed with keys only the site and its users hold, and the site's users are one directory every plugin shares. See encryption.

Everything rides the one connection a page shares with WordPlus's own plugins. That connection goes straight to a realtime server and moves to another one without a drop when a server restarts.

1. Install​

composer config repositories.wordplus composer https://packages.wordplus.cloud/composer
composer require wordplus/realtime

The package comes from WordPlus's own Composer repository, which the first line adds to your plugin's composer.json. Composer's autoloader includes realtime.php. Without Composer, unzip the package into your plugin and require its realtime.php from your plugin's main file.

Every plugin may bundle its own copy. The newest copy on the site answers wordplus_realtime(), and the newest connector serves every page, so plugins built on different versions work side by side. Call wordplus_realtime() from plugins_loaded on.

2. The site's credentials​

The SDK works on a site that has its WordPlus Cloud credentials: a site key and a secret. Every WordPlus plugin on the site shares them in the option wordplus_cloud_license.

  • A site running a WordPlus plugin (Better Messages, for example) has them once its licence is active.
  • Any other site connects once, from your plugin's settings page:
if ( ! wordplus_realtime()->available() ) {
	printf(
		'<a class="button" href="%s">%s</a>',
		esc_url( wordplus_realtime()->connect()->url( admin_url( 'admin.php?page=my-plugin' ) ) ),
		esc_html__( 'Connect to WordPlus Cloud', 'my-plugin' )
	);
}

The administrator approves in their WordPlus Cloud account, which uses one of their subscription's sites. They come back to your page with wordplus_realtime=connected, or denied or failed.

The secret never leaves the site's server, and it signs nothing itself. Tokens, publishes and calls each use their own key derived from it.

Only the site's own pages connect. A page on another address, a subdomain included, is refused with wrong_origin. So neither the site's key, which every page carries, nor its secret works on another website.

3. A first channel​

Own the channels whose names start with your prefix, and say who may join them:

add_action( 'plugins_loaded', function () {
	wordplus_realtime()->channel( 'private-orders-', function ( $user_id, $channel ) {
		$order = (int) substr( $channel, strlen( 'private-orders-' ) );
		return $user_id > 0 && my_shop_customer_of( $order ) === $user_id;
	} );
} );

Send an event from your server:

wordplus_realtime()->publish( 'private-orders-42', 'updated', array( 'status' => 'paid' ) );

Listen in the browser. Your script depends on the SDK's handle:

wp_enqueue_script( 'my-shop', plugins_url( 'shop.js', __FILE__ ), array( wordplus_realtime()->script() ), '1.0.0', true );
// Unset on a site without its credentials: there is nothing to listen to there.
if ( window.wordplusRealtimeConfig ) {
	const rt = wordplusRealtimeClient.channels( window.wordplusRealtimeConfig );

	rt.subscribe( 'private-orders-42' ).on( 'updated', ( data ) => showStatus( data.status ) );
}

script() always returns a handle. On a site without credentials it returns an empty one, so your script still loads and simply finds window.wordplusRealtimeConfig unset.

4. A first call​

Own the calls whose names start with your prefix:

add_action( 'plugins_loaded', function () {
	wordplus_realtime()->calls( 'support-', function ( $user_id, $call, $with ) {
		return my_support_may_call( $user_id, $call, $with );
	} );
} );

add_action( 'wp_enqueue_scripts', function () {
	if ( is_user_logged_in() ) {
		wordplus_realtime()->call_screen();
	}
} );

Put a call button on a page:

<wordplus-call to="34" call="support-42" type="video" name="Ann">Call Ann</wordplus-call>

User 34's every open page that loads the call screen rings. When they accept, the call window opens on both sides. calls.md explains the callback, and call-screen.md the elements.

What it needs​

  • WordPlus Cloud: a subscription that includes realtime (channels) and calls. Without them the connection is refused with not_included.
  • PHP 7.4 or newer.
  • Browsers: any current browser. Calls need WebRTC, which every current browser has.

Next​

  • Look at a complete plugin: examples/live-comments (channels and presence) and examples/video-support (calls, group calls and the call screen).
  • Coding with an AI agent? Point it at skills/wordplus-realtime.