WordPress Heartbeat API

I could not find any extensive documentation on the WordPress Heartbeat API, so I am writing here to remember what I have learned through various tutorials throughout the web.

The Heartbeat API is written in Javascript.  Think of it like a javascript function that gets run every 60 seconds (depending on the interval) which sends data via POST to the server and then the server returns a response.  All of which you can easily hook into.  It was introduced in WordPress 3.6.

Quick Examples

PHP

// server received whatever parameters from when javascript triggered the "heartbeat-send" event.
function myplugin_heartbeat_received( $response, $data ) {
if ( !empty( $data['myplugin_id'] ) ) {
$response['myplugin_got_it'] = true;
}
return $response;
}
add_filter( 'heartbeat_received', 'myplugin_heartbeat_received', 10, 2 );

Javascript

jQuery(document).ready(function($) {
wp.heartbeat.interval= 15;
// set some parameters when it's time to send data to the server
$(document).on('heartbeat-send.myplugin', function(e, data){
data['myplugin_id'] = my_id;
});

// do something when your page gets a response.
$(document).on('heartbeat-tick.myplugin', function(e, data){

if ( data.hasOwnProperty( 'myplugin_got_it' ) ) {
refreshPage();
}
});

});

Heartbeat Pulse Interval

The ‘heartbeat_settings’ filter gets applied in the ‘init’ hook, priority 0 in wp_default_scripts in wp-includes/script-loader.php.  So if you do use the hook on the server-side and want to only run it on certain pages, be prepared to parse the URL because a lot of WP functions aren’t available at that time.  Alternatively you can set the interval in javascript with wp.heartbeat.interval(15) where 15 is seconds.  Note some other tutorials say to use ‘fast’, ‘standard’, ‘slow’, but that didn’t work for me for some reason.

 

Tutorials

I found these tutorials to be the most helpful.

http://code.tutsplus.com/tutorials/the-heartbeat-api-getting-started–wp-32446

http://code.tutsplus.com/tutorials/the-heartbeat-api-changing-the-pulse–wp-32462

http://code.tutsplus.com/tutorials/heartbeat-api-using-heartbeat-in-a-plugin–wp-32496

 

Tagged with: , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.