キャッシュ済みページのパーソナライズされたフラグメント
静的キャッシュから配信されるページは、誰が見ても同じです。それがキャッシュの目的であり、同時に課題でもあります。ヘッダーにはログイン中の顧客に「こんにちは、Ada」と表示し、カートアイコンには商品数を3と表示したいものです。テンプレートで現在のユーザーに応じて分岐すると、キャッシュに保存された一人の訪問者への挨拶が全員に表示されるか、ページ全体をキャッシュ対象から外す必要があります。
Blockstudioの動的アイランドを使えば、この2つの問題を分けて扱えます。キャッシュされるHTMLには、キャッシュに適したプレースホルダーが含まれます。ページの読み込み後、小さなランタイムが訪問者自身のリクエストでWordPressに個人向けフラグメントを要求し、置き換えます。ページはキャッシュ可能なまま、フラグメントだけが動的になります。
このガイドでは、挨拶とカート数の2つのアイランドを作成し、キャッシュ済みページに含まれる内容、フラグメントリクエストの形式、エンドポイントが訪問者を識別する方法を順に説明します。WordPressを静的HTMLとして配信する]と併せてご覧ください。
動的アイランドの仕組み
- ブロックはマーカー要素内にプレースホルダーをレンダリングします。マーカーにはブロック名、許可リストに登録された属性、サーバー側で生成された署名が含まれます。
- レンダリングされたページにマーカーが含まれていると、Blockstudioがアイランドのランタイムを読み込みます。アイランドのないページでは、アイランド用JavaScriptは読み込まれません。
- ランタイムは準備完了のマーカーを集め、
/wp-json/blockstudio/v1/island/renderにまとめて1つのPOSTを送信します。 - エンドポイントは各署名を検証し、訪問者のリクエストコンテキストでブロックをレンダリングして、フラグメントを返します。
- ランタイムは各プレースホルダーを置き換え、イベントを発行します。
ブロックエディターでは、ブロックはプレースホルダーなしで通常どおりレンダリングされます。
ステップ1:挨拶ブロック
次の3つのファイルを作成してブロックを設定します。
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic"により、フラグメントリクエストを使うアイランドになります。
tagはマーカー要素を設定するため、アイランドをナビゲーションバー内にインラインで配置できます。attributesはフラグメントリクエストとともに送信されるブロック属性の許可リストです。リストにない属性は送信も署名もされません。cacheについては後ほど説明します。
キャッシュ済みページに含まれるのはプレースホルダーです。すべての訪問者に表示して問題ない内容にする必要があるため、ユーザーデータは含めません。「アカウント」リンクなら誰にでも使えます。
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
メインテンプレートで実際のフラグメントをレンダリングします。
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
ここで現在のユーザーに応じて分岐しても問題ありません。このテンプレートが実行されるのはフラグメントリクエストのときだけで、キャッシュ済みページの生成時には実行されないためです。
ヘッダーをレンダリングする場所に配置します。
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
ブロックタグも使えます。<bs:acme-greeting />または
<block name="acme/greeting" />です。
ステップ2:キャッシュ済みページに含まれる内容
サーバーでレンダリングすると、ブロックから出力されるのはマーカーとプレースホルダーだけです。
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
匿名の訪問者とログイン中のユーザーとしてそれぞれ1回レンダリングしても、2つの文字列はバイト単位で同一です。これは、serveLoggedInを有効にした静的プリレンダリングに必要な性質です。誰がレンダリングを開始しても保存されるドキュメントは同じで、個人情報が含まれることはありません。
ステップ3:フラグメントリクエスト
ランタイムは準備完了のアイランドを1つのリクエストにまとめて送信します。
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
レスポンスはclientIdをキーにします。ログイン中の訪問者の場合は次のようになります。
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
検証に失敗した項目は、HTMLの代わりにエラーコードを返しますが、バッチ内の残りの項目は処理されます。ここでは、2つ目の項目でguestLabelが対応する署名なしで変更され、3つ目では動的アイランドではないブロックが指定されています。
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
すべてのレスポンスにはCache-Control: no-store, no-cache, must-revalidate, max-age=0、Pragma: no-cache、X-Robots-Tag: noindexが含まれます。エンドポイントは/wp-json配下にあり、静的プリレンダリングでは常にバイパスされます。そのため、オリジンキャッシュも、オリジンのヘッダーに従うCDNもフラグメントを保存しません。
訪問者の識別
ランタイムはcredentials: 'same-origin'を付けてリクエストを送信するため、ブラウザーはログイン用のWordPress Cookieを含めます。WordPress REST APIは通常、nonceなしではCookie認証を無視します。また、キャッシュ済みページにnonceを含めることはできません。アイランドのエンドポイントはこの問題に独自に対応します。同一オリジンのブラウザーリクエストでは、logged_in Cookieを検証し、そのユーザーを復元してからレンダリングします。
同一オリジンかどうかはSec-Fetch-Siteヘッダーと、存在する場合はOriginヘッダーをhome_url()と比較して判断します。Cookieが含まれていても別オリジンからのリクエストは匿名としてレンダリングされるため、別サイトから訪問者の個人向けフラグメントが表示されることはありません。具体的には次のとおりです。
| リクエスト | レンダリング時のユーザー |
|---|---|
| 有効なログインCookieを伴う同一オリジンのfetch | ログイン中のユーザー |
| 同じCookieを伴うクロスオリジンリクエスト | 匿名 |
| Cookieなし | 匿名 |
これはどのページですか?
フラグメントでページの識別情報が必要な場合は、blockstudio.islandに"context": trueを追加します。するとマーカーは、属性とともに、クエリされたページの投稿IDと投稿タイプに署名します。フラグメント内では、$block['postId']、$block['postType']、get_the_ID()、get_queried_object_id()がそのページを参照します。クエリループ内でも、ループ項目ではなく、外側のクエリ対象ページを指します。
ページコンテキストはオプトイン方式で、フラグメントキャッシュキーの一部でもあります。エンドポイントはキャッシュ済みのフラグメントであってもアクセスを再確認するため、署名付きマーカーによって、後から非公開またはパスワード保護されたページが公開されることはありません。設定とセキュリティの詳細はページコンテキストを参照してください。任意のURLやクエリパラメーターは再利用されません。
ステップ4:自動更新されるカート数
2つ目のアイランドでは、もう1種類のプレースホルダーと2つのランタイムオプションを紹介します。別ファイルでプレースホルダーを定義する代わりに、テンプレートで$isIslandPlaceholderを確認します。
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
どのテンプレート言語でも同じフラグを使えます。isIsland、isIslandPlaceholder、isIslandFragment、islandPhase("normal"、"hydrate"、"placeholder"、"fragment")です。ここではacme/cart_countフィルターからカート数を取得し、コマースコードがその値を設定します。値が3の場合、エンドポイントは次の内容を返します。
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible"はIntersectionObserverを使い、マーカーがビューポートに入るまでリクエストを遅らせます。表示されたアイランドが同時に現れた場合は、引き続き1つのリクエストにまとめられます。eventにはアイランドを再取得するウィンドウイベントを指定します。そのため、カートへの追加処理の後は、スクリプトからイベントを通知するだけで済みます。
window.dispatchEvent(new Event('acme:cart-updated'));
フロントエンドコードでのイベント処理
イベントはマーカーからバブリングするため、documentに1つリスナーを設定すれば、すべてのアイランドを処理できます。event.detail.nameにはブロック名が格納されています。
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
置き換え後、ランタイムはまずblockstudio:island:rendered、続いてblockstudio:island:hydrateを発行します。失敗した場合はプレースホルダーがそのまま残り、blockstudio:island:errorが発行されます。ハイドレーション済みのアイランド("island": "hydrate")はリクエストを完全に省略します。完全なHTMLがページ内にあり、hydrateイベントだけを受け取るため、タブなどキャッシュに適したインタラクティブなブロックに向いています。
フラグメントのキャッシュ
デフォルトでは、フラグメントはリクエストごとにレンダリングされます。上記の挨拶ブロックでは、短期間のキャッシュを有効にしています。
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user"ではキャッシュ済みフラグメントをWordPressユーザーIDごとに分けます。匿名リクエストはキャッシュされないため、複数の匿名訪問者がユーザー向けのエントリーを共有することはありません。per: "global"では同じブロックと属性のフラグメントを共有するため、在庫数など、動的でも個人向けではないコンテンツに適しています。ttlのデフォルトは60秒で、cache: trueは全体で60秒間有効なキャッシュです。
セキュリティモデル
エンドポイントは公開されていますが、あらゆるブロックをレンダリングするものではありません。次の条件をすべて満たすエントリーだけをレンダリングします。
- ブロックが登録済みで動的であり、
island.modeがdynamicに設定されている - 署名がブロック名とフィルターを通過した属性に一致している。対象となるのは、ブロックスキーマとアイランドの許可リストの両方に含まれるキーのみ
署名は、正規化されたブロック名と属性に対するHMAC-SHA256で、配信サイトのauthソルトを鍵として生成されます。署名はそのサイトでのレンダリング時に作成され、テーマに埋め込まれることはありません。ここから2つの点がわかります。ステージング環境でレンダリングしたドキュメントにはステージング環境の署名が含まれるため、配信元のサイトでドキュメントをレンダリングしてください。また、WordPressソルトをローテーションすると、保存済みドキュメントのすべての署名が無効になるため、ローテーション後に静的プリレンダリングをパージしてください。
1回のリクエストで処理できるアイランドは最大50個です。超過するとHTTP 413が返されます。blockstudio/islands/max_per_requestで上限を変更できます。別の方式が必要なホスト向けに、署名フック(blockstudio/islands/signature_payload、blockstudio/islands/signature、blockstudio/islands/verify_signature)が用意されています。
アイランドを使わないほうがよい場合
フラグメントは初期HTMLに含まれないため、クローラーには認識されません。SEOに関わるコンテンツは通常のレンダリングに含めてください。動的アイランドは、ページのシェルを配信した後に表示できるもの、たとえばアカウントへのリンク、カートの状態、おすすめ商品、権限で制御されるコントロールに使います。アカウントダッシュボードのようにページ全体が個人向けの場合は、代わりにそのパスをdynamicPathsに記載して、ページを動的にレンダリングしてください。
次のステップ
- Islands リファレンス:すべてのオプション、プレースホルダーの検索順序、PHP API、フック。
- WordPress を静的な HTML として配信:これらの Islands 向けに設計されたキャッシュ。
- 静的プリレンダリングのリファレンス:
serveLoggedIn、動的パス、早期配信。 - インタラクティブコンポーネント:マウントイベント以上の処理が必要なブロックのクライアント側の動作。