Understanding WordPress Heartbeat API

The WordPress Heartbeat API is a powerful tool that allows developers to communicate between the user's browser and the server, enabling "near real-time" interactions without reloading the entire page. This can be especially useful for plugins and themes that require frequent updates or user interactions, such as chat apps or collaborative editing tools.

Understand the Heartbeat API

Before diving into the Heartbeat API, it's important to understand what it does and how it works. The Heartbeat API uses AJAX to send a request to the server at regular intervals (typically every 15-60 seconds) and receives a response with data or instructions to update the page accordingly.

The Heartbeat API is built into WordPress core and can be accessed through:

• `wp.heartbeat` JavaScript object.
• `wp_ajax_heartbeat` server-side actions.
• `wp_ajax_nopriv_heartbeat` server-side actions.

Using the heartbeat API

Step 1: Add Custom Data to Heartbeat Data

To send custom data to the server using the Heartbeat API, you need to add additional fields to the data that will be sent. This can be done by attaching a callback function to the 'heartbeat-send' event using jQuery.

jQuery(document).on('heartbeat-send', function (event, data) {
    // Add additional data to Heartbeat data.
    data.my_custom_data = 'some data';
});{        

Step 2: Receive and Respond on the Server

On the server side, you need to detect the custom data that was sent in Step 1 and add additional data to the response.

function myplugin_heartbeat_received($response, $data) 
? // Check if custom data was actually sent
? if (! isset($data['my_custom_data'])) {
? ? return $response;
? }

  $custom_data = $data['my_custom_data'];

? // Add additional data to the response
? $response['custom_data_response'] = 'Data received!';


? // Process the custom data
? $processed_data = myplugin_process_data($custom_data);


? // Add the processed data to the response
? $response['processed_data'] = $processed_data;

? return $response;
}
add_filter('heartbeat_received', 'myplugin_heartbeat_received', 10, 2);


function myplugin_process_data($data) {
? // Process the data here
? return 'Processed data: ' . json_encode($data);
}        

Step 3: Process the Response in JS

Finally, you need to handle the response on the client side.

jQuery(document).on('heartbeat-tick', function(event, data) {
  if (data.hasOwnProperty('custom_data_response')) {
    console.log(data.custom_data_response);
  }

  if (data.hasOwnProperty('processed_data')) {
    console.log(data.processed_data);
  }
});        

And that's it! With these steps, you can send custom data to the server using the Heartbeat API, process the data on the server side, and receive and handle the response on the client side.

Choose the Right Frequency and Location

One of the most important considerations when using the Heartbeat API is the frequency and location of the requests. The default frequency is 15 seconds, but this can be adjusted using the heartbeat_settings filter.

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