みなさんこんにちは！速ラボ編集部です。
今回は、WordPressのハートビートAPI(Heartbeat API)とは？APIの使い方や仕組みについて徹底解説したいと思います。
ハートビートAPIは、WordPressコアで標準で使われているAPIになりますが、このAPIを活用して、独自にさまざまな機能を実装することが可能です。
WordPressでのテーマやプラグインの開発などで主に利用できるかと思いますが、当記事だけでハートビートAPIの仕組みや実装方法についてわかるように構成しておりますので、よろしければぜひお仕事などでご活用いただけますと幸いです。
ハートビートAPI(Heartbeat API)とは
ハートビートAPI(Heartbeat API)とは、WordPressに標準搭載されている仕組みのひとつで、ブラウザとサーバーの間で定期的に通信を行い、リアルタイム性を必要とする機能をサポートするためのAPIです。
具体的には、管理画面での投稿の自動保存や他ユーザーとの同時編集の検出、ログインセッションの維持、プラグインやテーマによる非同期通信処理などに利用されています。
心臓の鼓動のように一定間隔でサーバーとやり取りを行うことから「ハートビート」という名前が付けられたのかもしれませんね。
このAPIを活用することで、開発者はWordPressにリアルタイム性をもたせた拡張機能を実装できる一方で、通信が頻発するためサイトのパフォーマンスに影響を与える場合もあります。
そのため、必要に応じて間隔の調整や無効化を検討することが推奨されます。
詳しい説明は以下の公式ページでご確認できるので、よろしければご確認ください。
ハートビートAPI(Heartbeat API)の実装方法
次は、ハートビートAPI(Heartbeat API)の実装方法について解説いたします。
まず実装の前に、そもそもハートビートAPIがなんのどの部分を対象に使えるものなのかを説明しておきたいと思います。
通常WordPressでは、筆者が確認する限り以下の管理画面ページにてハートビートAPIによってadmin-ajax.phpへの繰り返しの通信が発生しておりました。
- ブロックエディタ
- 投稿一覧
- 固定ページ一覧
- 旧ブロックパターン
ほとんどURLが「edit.php?post_type=〇〇〇〇」である投稿タイプ系のページでハートビートAPIが処理されているイメージになるかと思います。
ご確認いただく場合は、「F12」または「右クリック → 検証」で開発者ツールを開いていただき、「Network」タブを開き、フィルターで「admin-ajax.php」を検索していただくと、下図のようにadmin-ajax.phpが繰り返し追加されていく挙動を確認できます。
実際に見ると、数秒〜数十秒ごとに「action=heartbeat」という通信が出ているか確認できるかと思います。
admin-ajax.phpという項目をクリックすると、下図のように「ペイロード」を閲覧できて、「action」が「heartbeat」となっていることが確認できるかと思います。
ハートビートAPIを利用すれば、この通信を制御することが可能となります。
次からは基本となる実装方法について解説いたしますので、しっかり把握しておきましょう。
ハートビートAPIを完全無効化（非推奨）
非推奨ではありますが、ハートビートAPIを完全無効化する場合は以下のコードになります。
動作を確認する場合は、以下のコードをfunctions.phpへコピー＆ペーストしてください。
<?php
// ハートビートAPIを完全無効化
add_action( 'init', 'my_disable_heartbeat_all', 1 );
function my_disable_heartbeat_all() {
wp_deregister_script( 'heartbeat' );
}上記コードは、WordPressの初期化処理（initアクション）で、独自のmy_disable_heartbeat_all()関数を実行するよう登録しています。
my_disable_heartbeat_all()関数の中では、wp_deregister_script( ‘heartbeat’ )関数が呼び出され、WordPressに登録されている「heartbeat」という名前のJavaScriptファイルが解除されます。
具体的には以下の出力が全ページで消えます。
<script id="heartbeat-js-extra">
var heartbeatSettings = {"nonce":"acc2896247"};
</script>
<script src="https://〇〇/wp-includes/js/heartbeat.min.js?ver=6.8.2&fver=20241114075748" id="heartbeat-js"></script>その結果、管理画面やフロントでのハートビートAPIによる自動通信機能が完全に停止します。
ペーストが完了したら、WordPress管理画面左メニュー「投稿」の「投稿一覧」をご確認ください。
そしてブラウザの開発者ツールを開いていただくと、下図のようにハートビートAPIの通信が発生していないことを確認できるかと思います。
また、例えばブロックエディタなど他のすべての管理画面ページでも通信が発生していないことを確認できるかと思います。
ブロックエディタでは、ハートビートAPIを利用して色々な処理を行なっているため、ブロックエディタで通信を発生させない処理はおすすめできませんので、ここでのコードはあくまでも非推奨ということでご認識ください。
特定ページで無効化する方法
次はより実用的な実装方法として、特定ページで無効化する方法について解説いたします。
動作を確認する場合は、以下のコードをfunctions.phpへコピー＆ペーストしてください。
<?php
// 投稿編集画面以外ではハートビートを停止
add_action( 'init', 'my_disable_heartbeat', 1 );
function my_disable_heartbeat() {
global $pagenow;
if ( 'post.php' != $pagenow && 'post-new.php' != $pagenow ) {
wp_deregister_script( 'heartbeat' );
}
}上記コードは、WordPressの初期化処理（initアクション）が実行されるタイミングで、独自のmy_disable_heartbeat()関数を呼び出すよう登録しています。
関数内ではまず、現在表示している管理画面のページ情報を示すグローバル変数$pagenowを取得します。
そして、ページがpost.php（既存投稿の編集画面）でもpost-new.php（新規投稿の作成画面）でもない場合に、wp_deregister_script( ‘heartbeat’ )関数を実行します。
このwp_deregister_script()関数によってheartbeat.js（heartbeat.min.js）が登録解除され、ハートビートAPIはそのページでは動作しなくなります。
ブロックエディタではこの処理をしないこととしておりますが、ブロックエディタではハートビートAPIを色々と利用する機能があるため、このようにページによって制御する形で実装するようにしましょう。
ハートビートAPIの間隔を調整してサーバー負荷を軽減する方法
次にまた、実用的なコードとして、ハートビートAPIの間隔を調整してサーバー負荷を軽減する方法について解説いたします。
動作を確認する場合は、以下のコードをfunctions.phpへコピー＆ペーストしてください。
<?php
// ハートビートの間隔を60秒に変更
add_filter( 'heartbeat_settings', 'my_heartbeat_settings' );
function my_heartbeat_settings( $settings ) {
$settings['interval'] = 60; // 秒数
return $settings;
}このコードは、WordPressのハートビートAPIに関する設定を変更するために、「heartbeat_settings」フィルターを利用しています。
まず、add_filter()関数によって「heartbeat_settings」フィルターに独自のmy_heartbeat_settings()関数を登録します。
この関数は、ハートビートAPIの設定を保持する$settings配列を受け取り、その中のinterval（通信間隔）の値を60に書き換えます。
変更後の$settingsを返すことで、ブラウザからサーバーへのハートビート通信が 15秒ごと（デフォルト）から60秒ごと に変更されます。
ブラウザの開発者ツールを開いていただくと、下図のようにハートビートAPIの通信が60秒ごとになっていることを確認できるかと思います。
これによってサーバーへの負荷が軽減され、通信の面でパフォーマンスを改善できる可能性があります。
つまり、AWSなどクラウド環境を利用してWordPressを立ち上げている場合、インフラコスト（CPU、DB、転送料、スケールアウト回数）を間接的に削減できます。
また、レンタルサーバーを利用の場合も、リソース制限や負荷によるエラーを防ぎ、管理画面の安定性が増します。
ただし、過度に間隔を伸ばすと自動保存や編集ロック検出が遅れる ため、完全停止ではなく「60秒に変更」などの調整が現実的かと思います。
ハートビートAPI(Heartbeat API)での本格的な実装方法
今度はもう少し実用性を上げて、ハートビートAPI(Heartbeat API)での本格的な実装方法について解説したいと思います。
サンプルとして、応用カスタマイズしやすいWordPressのハートビートAPIで管理画面とサーバーの間で定期的なデータ送受信を行う仕組みを実装したいと思います。
以下のコードを、functions.phpにコピー＆ペーストしてください。
ペーストしていただくテーマは無料の公開されているものでも自作のものでもなんでも問題ありません。
<?php
// ハートビートの送信間隔を変更（例: 15秒ごと）
add_filter( 'heartbeat_settings', function( $settings ) {
$settings['interval'] = 5; // デフォルトは60秒
return $settings;
});
// サーバー側でハートビートを受け取り、データを返す
add_filter( 'heartbeat_received', function( $response, $data ) {
if ( isset( $data['my_heartbeat_test'] ) ) {
$response['my_heartbeat_response'] = 'サーバーからの応答時間: ' . date( 'H:i:s' );
}
return $response;
}, 10, 2 );
// 管理画面にJSを追加してハートビートを送信
add_action( 'admin_enqueue_scripts', function() {
add_action( 'admin_print_footer_scripts', function() {
?>
<script>
(function($){
// 15秒ごとにデータ送信
$(document).on('heartbeat-send', function(e, data) {
data['my_heartbeat_test'] = 'ping';
});
// サーバーからの応答を受け取る
$(document).on('heartbeat-tick', function(e, data) {
if ( data['my_heartbeat_response'] ) {
console.log('Heartbeat Response:', data['my_heartbeat_response']);
}
});
})(jQuery);
</script>
<?php
});
});上記コードは、WordPressのハートビートAPIを利用して、管理画面とサーバーの間で定期的なデータ送受信を行う仕組みを実装しています。
まず、ハートビートの送信間隔を通常の60秒から5秒に変更しています。これにより、ブラウザからサーバーへより短い間隔で通信が行われるようになります。
次に、サーバー側では受信したデータを確認し、特定のキーが含まれている場合には現在時刻をレスポンスとして返すようにしています。これによって、サーバーがクライアントからのリクエストを正しく受け取ったかどうかを確認できます。
さらに、管理画面にはJavaScriptが追加され、ハートビートAPIのイベントに基づいて処理が行われます。ハートビート送信時には特定のデータをサーバーへ送信し、サーバーから応答があればそれを受け取り、ブラウザのコンソールに結果を表示します。
つまり、このコード全体の動作は、一定間隔ごとにブラウザとサーバー間でデータをやり取りし、その応答を管理画面でリアルタイムに確認できる仕組みを提供している、という内容になります。
ペーストが完了したら、管理画面を確認してブラウザの開発者ツールを確認してみてください。
すると、下図のようにコンソールにフロントから送信されたデータがサーバーに送られ、加工されたデータがまたフロントに返却されて処理されているのがわかったかと思います。
この仕組みを利用して、「フロント側でイベントを送信」→「サーバーで必要な処理」→「結果を返却」→「UIへ反映」 という流れで構成された機能を実装することが可能です。
あとはご自身で、思いつく限りの機能にアレンジしてカスタマイズしてみてください。
ハートビートAPI(Heartbeat API)のフックやJSイベントについて
次は、ハートビートAPI(Heartbeat API)のフックやJSのイベントについて解説いたします。
ここでしっかり把握しておくことで、実際に実装する際にスムーズに対応することが可能です。
ハートビートAPIに関するイベントとフックについては、主に以下になります。
- heartbeat_settingsフック
- heartbeat_receivedフック
- JavaScriptでのheartbeat-sendイベント
- JavaScriptでのheartbeat-tickイベント
それぞれ解説いたします。
heartbeat_settingsフック
heartbeat_settingsフックは、ハートビートAPIの挙動（間隔や設定）をクライアント側に渡す直前に呼ばれるフィルター です。
これを利用すると、ブラウザでの通信間隔や設定を動的に変更できます。
<?php
// ハートビート間隔を60秒に変更
add_filter( 'heartbeat_settings', 'my_heartbeat_settings' );
function my_heartbeat_settings( $settings ) {
$settings['interval'] = 60; // デフォルト15秒 → 60秒
return $settings;
}主な用途は以下になりますので、ご確認ください。
- 通信間隔の調整（サーバー負荷を下げたい場合など）
- 特定ページだけ設定を変更する（例：ダッシュボードでは60秒、投稿編集では15秒）
- クライアント側に渡すheartbeatの動作設定を制御する
また、heartbeat_settingsフックの詳しい説明は以下の公式ページでご確認できるので、よろしければご確認ください。
heartbeat_receivedフック
heartbeat_receivedフックは、サーバーがハートビートリクエストを受け取った後に呼ばれるアクションフック です。
ここでリクエストデータを読み取り、レスポンスに追加することで、フロントエンドに独自の情報を返せます。
<?php
// サーバーでデータを処理して返す
add_filter( 'heartbeat_received', 'my_heartbeat_received', 10, 2 );
function my_heartbeat_received( $response, $data ) {
if ( ! empty( $data['my_custom_data'] ) ) {
// 受け取ったデータを加工して返す
$response['my_custom_data'] = 'サーバーで処理しました: ' . $data['my_custom_data'];
}
return $response;
}主な用途は以下になりますので、ご確認ください。
- クライアントから送られた独自データをサーバーで処理
- 処理結果をレスポンスに追加してブラウザに返す
- リアルタイム機能（チャット、通知、オンラインユーザー管理など）の基盤に利用可能
また、heartbeat_receivedフックの詳しい説明は以下の公式ページでご確認できるので、よろしければご確認ください。
JavaScriptでのheartbeat-sendイベント
JavaScript（jQuery）での「heartbeat-send」イベントは、WordPressのハートビートAPIが サーバーにリクエストを送信する直前に発火するイベントです。
このイベントを利用することで、開発者は追加のデータをサーバーへ送信することができます。
jQuery(document).on('heartbeat-send', function(event, data) {
// サーバーに送るデータを追加
data.my_custom_data = 'Hello Server!';
});主な用途は以下になりますので、ご確認ください。
- 独自のデータをadmin-ajax.php経由でサーバーに送る
- プラグインやテーマの状態をサーバーに通知する
- リアルタイムで必要な情報をサーバー側に蓄積・処理させる
JavaScriptでのheartbeat-tickイベント
JavaScript（jQuery）での「heartbeat-tick」イベントは、WordPressのハートビートAPIがサーバーからレスポンスを受け取った直後に発火するイベントです。
このイベントを利用することで、サーバーから返ってきたデータをフロント側で処理できます。
jQuery(document).on('heartbeat-tick', function(event, data) {
if ( data.my_custom_data ) {
console.log('サーバーからのレスポンス:', data.my_custom_data);
}
});主な用途は以下になりますので、ご確認ください。
- サーバーから返されたデータを画面に反映する
- リアルタイム通知やメッセージ表示機能
- 投稿ロックやセッション情報の更新状態をユーザーに知らせる
まとめ
今回は、WordPressのハートビートAPI（Heartbeat API）について、その仕組みや使い方、実装方法まで徹底的に解説しました。
ハートビートAPIはWordPressコアで標準搭載されており、テーマやプラグイン開発の際に活用することで、管理画面やフロント画面でのリアルタイム通信や通知機能など、さまざまな独自機能を実装することが可能です。
本記事の内容を理解していただくことで、ハートビートAPIの基本的な仕組みから、送信間隔の調整やサーバーとのデータ送受信、UIへの反映まで応用することができます。
ぜひ、テーマやプラグイン開発、管理画面の改善などのお仕事にお役立てください。
コメント