Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
  1. Code
  2. Creative Coding

Heartbeat API: Using Heartbeat in a Plugin


In this tutorial we're going to create a simple plugin which uses the Heartbeat API. Our plugin will alert logged in users, via a growl-like notification, whenever another user logs in or out of the site.

Since this tutorial is focussed on the Heartbeat API, I shall leave out details about creating the plugin header or file structure: the plugin is very simple, and you can examine the source code in full at this GitHub repository.

A user will be deemed "logged in" when they log in and have been active within the last 24 hours. If a user logs out or is not active for 24 hours, they'll be considered to be offline. We'll keep tabs on the user's 'online' status and 'last active' timestamp to help determine who's currently online.

Logging-in and Logging-out

First we'll create a couple of functions hooked into wp_login and wp_logout hooks. These are triggered when a user logs in/out of WordPress. When a user logs in, we'll update their log in status (stored as user meta) to 'true' and update their last active timestamp.

Similarly, when a user logs out, we'll update their online status to false:

Who's Online?

Now let's create a function which returns an array of usernames of active users, indexed by user ID. We'll use the get_users() function to query all users who have been active in the last 24 hours (using the whoisonline_last_active meta key).

We'll then discard any users who have logged out by checking the whoisonline_is_online user / meta data.

Preparing for the Heartbeat API

Before we deal with the client-side part of the Heaertbeat API, let's deal with the server's response to a request for 'who's online'. As was covered in part 1 of this series, we'll hook onto the filter heartbeat_received (we don't need to trigger this for logged out users so won't use the heartbeat_nopriv_received filter).

First, we'll update the current user's activity timestamp, and ensure their status is set to 'online'. Next we'll check that a request for 'who's online' data has been made by looking for the who-is-online key (which we'll use later) in the received $data.

If it has, we'll respond with an array of logged in users of the form:

As returned by who_is_online().

Heartbeat API

Now create the JavaScript file who-is-online.js file in the root of your plugin folder. Below is the outline of the file.

First, we initiate our global variable whoisonline. whoisonline.online and whoisonline.onlinePrev are both 'associative arrays' (strictly speaking, in terms of JavaScript, they're objects) of users logins, indexed by user ID – corresponding to those users who are 'online' at the current / previous beat. This is used to determine when a user has logged in or out.

We then initiate our request for data on who's online with wp.heartbeat.enqueue and listen for the response by binding a callback to the event heartbeat-tick.whoisonline. In that callback we check for data returned by the server, perform any necessary actions and then ensure our request for data is queued for the next beat.

Now, let's fill in the details of the logic inside our heartbeat-tick.whoisonline callback. Whenever data is received from the server we first check that it contains an array of logged in users (which would be given by the key 'whoisonline'), by checking data.hasOwnProperty( 'whoisonline' ). If so...

  • Update whoisonline.onlinePrev to reflect who was online at the last beat, and whoisonline.online to reflect who is online at the current beat.
  • Check for user IDs that appear in whoisonline.online, but are not in whoisonline.onlinePrev. These users have just logged in.
  • Check for user IDs that appear in whoisonline.onlinePrev, but are not in whoisonline.online. These users have just logged out.

The finished JavaScript file then looks like:

Loading Our Scripts and Styles

This plugin will make use of the jQuery Notice add-on by Tim Benniks - a lightweight growl-like notification plugin for jQuery. Simply download it, and extract to the root of your plugin (it should consist of only two files: jquery.notice.js and jquery.notice.css)

Now that the jQuery plugin has been added, the last piece of the puzzle is to enqueue the necessary scripts and styles. We want this plugin to function both on the front-end and admin side, so we'll use both the admin_enqueue_scripts and wp_enqueue_scripts hook, but we only want to load the script for logged in users.

And that's the finished plugin.

You can see the code in full at this GitHub repository. There's plenty of room for improvement here (for instance display a list of users, and when they were last active), but hopefully this relatively simple plugin has demonstrated how the Heartbeat API works.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.