ハートビート API は、WordPress に組み込まれたシンプルなサーバーポーリング API で、フロントエンドの更新をほぼリアルタイムで行うことができます。
しくみ
ページがロードされると、15～120秒ごとに、クライアント側のハートビート・コードは、(「ティック」と呼ばれる) 実行間隔を設定します。実行されると、ハートビートは、jQuery イベントで送信するデータを収集し、これをサーバーに送信してレスポンスを待ちます。サーバーでは、admin-ajax ハンドラーが渡されたデータを受け取り、レスポンスを準備し、レスポンスをフィルタリングして、JSON フォーマットでデータを返します。クライアントは、このデータを受け取り、データを受け取ったことを示す最後の jQuery イベントを発生させます。
カスタム・ハートビート・イベントの基本的なプロセスは、以下の通りです:
- 送信するデータに、フィールドを追加します (JS
heartbeat-sendイベント)。 - PHP で送信済みフィールドを検出し、レスポンスフィールドを追加します (
heartbeat_receivedフィルター)。 - 返されたデータを JS で処理します (JS
heartbeat-tick)。
(必要な機能に応じて、これらのイベントのうち、1つまたは2つだけを使用できます)
API の使用
ハートビート API を使用するには、2つの別々な機能が必要です: JavaScript での送受信コールバック、そして、PHP で渡されたデータを処理するサーバー側フィルターです。
サーバーへのデータ送信
ハートビートがサーバーにデータを送信する際に、カスタムデータを含めることができます。これは、サーバーに送信したい任意のデータでも、データを期待していることを示す単純な true 値でもかまいません。
jQuery( document ).on( 'heartbeat-send', function ( event, data ) {
// Add additional data to Heartbeat data.
data.myplugin_customfield = 'some_data';
});
サーバーでの受信と応答
サーバー側では、このデータを検出し、レスポンスに追加データを加えることができます。
/**
* Receive Heartbeat data and respond.
*
* Processes data received via a Heartbeat request, and returns additional data to pass back to the front end.
*
* @param array $response Heartbeat response data to pass back to front end.
* @param array $data Data received from the front end (unslashed).
*
* @return array
*/
function myplugin_receive_heartbeat( array $response, array $data ) {
// If we didn't receive our data, don't send any back.
if ( empty( $data['myplugin_customfield'] ) ) {
return $response;
}
// Calculate our data and pass it back. For this example, we'll hash it.
$received_data = $data['myplugin_customfield'];
$response['myplugin_customfield_hashed'] = sha1( $received_data );
return $response;
}
add_filter( 'heartbeat_received', 'myplugin_receive_heartbeat', 10, 2 );
フロントエンドに戻れば、このデータを受け取ることができます。
jQuery( document ).on( 'heartbeat-tick', function ( event, data ) {
// Check for our data, and use it.
if ( ! data.myplugin_customfield_hashed ) {
return;
}
alert( 'The hash is ' + data.myplugin_customfield_hashed );
});
すべての機能が、これら3つのステップすべてを必要とするわけではありません。たとえば、サーバーにデータを送信する必要がない場合は、後の2つのステップだけを使用できます。