In the first part of this series we looked at the basics of the Heartbeat API, and how it can be implemented in a plugin. In this tutorial we'll be looking at how you can change the "pulse" of the Heartbeat.

By default the WordPress heart beats once every 15 seconds. You can lower that rate to anything down to one beat every minute. Alternatively you can temporarily increase the rate to one beat every 5 seconds – but only temporarily for two and half minutes before it is reset to the the 'standard' beat: "4 BPM".

Change the Default Pulse

To change the default pulse you can use the wp_heartbeat_filter filter which filters the initial settings of the Heartbeat API. This filter does not allow to you initially set the pulse to 'fast': instead you can only specify a number between 15 and 60 (interval between beats in seconds).

function wptuts_heartbeat_settings( $settings ) {
	$settings['interval'] = 60; //Anything between 15-60
	return $settings;
}
add_filter( 'heartbeat_settings', 'wptuts_heartbeat_settings' );

Turn Off Auto-Start

Although requests are only sent to the server when there is data to send, Hearbeat starts running automatically when the page loads. You can turn auto-start off from the default Heartbeat settings:

function wptuts_heartbeat_settings( $settings ) {
	$settings['autostart'] = false;
	return $settings;
}
add_filter( 'heartbeat_settings', 'wptuts_heartbeat_settings' );

Switching from server-side to the browser, Heartbeat will then only start running if:

wp.heartbeat.start();

is called. You can also turn off Heartbeat client-side too:

wp.heartbeat.stop();

Change the Pulse Client-Side

As well as turning Heartbeat on and off, you can manipulate the beat of the pulse (for example) in response to certain events triggered by the user. For instance, you may listen for when the user starts an activity that requires more regular communication with the server – and so temporarily increase the rate.

From within your JavaScript script:

// 1 beat every 5 seconds for a maximum of two and half minutes
wp.heartbeat.interval( 'fast' );

// 1 beat every 60 seconds
wp.heartbeat.interval( 'slow' );

// 1 beat every 15 seconds
wp.heartbeat.interval( 'standard' );

Change the Pulse Server-Side

As well as changing the pulse browser-side, we can also do this each time the browser communicates with the server. This is done by setting 'heartbeat_interval' in the response – it can be one of 'fast', 'slow' or 'standard'.

function wptuts_respond_to_browser( $response, $data, $screen_id ) {
	if ( isset( $data['wptuts-plugin'] ) ) {
		// Plug-in data being sent to browser
		$response['wptuts-plugin'] = array(
			'hello' => 'world'
		);

		// Slow the hearbeat
		$response['heartbeat_interval'] = 'slow';
	}
	return $response;
}
add_filter( 'heartbeat_received', 'wptuts_respond_to_browser', 10, 3 ); // Logged in users
add_filter( 'heartbeat_nopriv_received', 'wptuts_respond_to_browser', 10, 3 ); // Logged out users

User Inactivity

The Heartbeat API also adjusts the beat according to a user's activity. WordPress checks user activity every 30 seconds, if after 5 minutes, there's been no keyboard or mouse activity, the beat is reduced to one beat every hundred seconds. This is done regardless of what it may have been set to by a plugin.

In the final part of this series we'll create a simple working example of a plugin using the new Heartbeat API. We'll create a plugin which gives users 'live' updates on when users log in and out of WordPress.