Lewati ke konten

Fragmen Personal di Halaman yang Di-cache

Halaman yang disajikan dari cache statis sama untuk semua orang. Itulah tujuan caching, sekaligus masalahnya: header ingin mengatakan “Hai, Ada” kepada pelanggan yang masuk, dan ikon keranjang ingin menampilkan tiga item. Jika template menyesuaikan tampilan berdasarkan pengguna saat ini, cache akan menyimpan sapaan seorang pengunjung untuk semua orang atau harus melewati halaman itu sepenuhnya.

Pulau dinamis Blockstudio memisahkan dua kebutuhan tersebut. HTML yang di-cache berisi placeholder yang aman untuk cache. Setelah halaman dimuat, runtime kecil meminta fragmen personal kepada WordPress dalam permintaan pengunjung itu sendiri, lalu menggantinya. Halaman tetap dapat di-cache, dan hanya fragmennya yang bersifat dinamis.

Panduan ini membuat dua pulau, sapaan dan jumlah keranjang, serta menjelaskan isi halaman yang di-cache, bentuk permintaan fragmen, dan cara endpoint mengenali pengunjung. Panduan ini melengkapi Menyajikan WordPress sebagai HTML.

Cara kerja pulau dinamis

  1. Block merender placeholder di dalam elemen penanda. Penanda memuat nama block, atribut yang diizinkan, dan tanda tangan yang dibuat server.
  2. Karena halaman hasil render memuat penanda, Blockstudio menyisipkan runtime pulau. Halaman tanpa pulau tidak memuat JavaScript pulau.
  3. Runtime mengumpulkan penanda yang siap dan mengirim satu POST gabungan ke /wp-json/blockstudio/v1/island/render.
  4. Endpoint memverifikasi setiap tanda tangan, merender block dalam konteks permintaan pengunjung, lalu mengembalikan fragmen.
  5. Runtime mengganti setiap placeholder dan memicu event.

Di editor block, block dirender secara normal tanpa placeholder.

Langkah 1: Block sapaan

Buat block dengan tiga file:

Kode
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "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" yang menjadikannya pulau dengan permintaan fragmen. tag menetapkan elemen penanda agar pulau dapat ditempatkan sebaris di bilah navigasi. attributes adalah daftar izin atribut block yang disertakan dalam permintaan fragmen; apa pun yang tidak tercantum tidak dikirim maupun ditandatangani. cache dibahas lebih lanjut di bawah.

Halaman yang di-cache berisi placeholder. Placeholder harus aman ditampilkan kepada semua pengunjung, jadi tidak boleh memuat data pengguna. Tautan “Akun” dapat digunakan oleh semua orang:

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

Template utama merender fragmen sebenarnya:

PHP
<?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; ?>

Menyesuaikan tampilan berdasarkan pengguna saat ini aman dilakukan di sini: template ini hanya dijalankan untuk permintaan fragmen, tidak pernah untuk halaman yang di-cache.

Tempatkan di mana pun header dirender:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Tag block juga bisa digunakan: <bs:acme-greeting /> atau <block name="acme/greeting" />.

Langkah 2: Isi halaman yang di-cache

Saat dirender di server, block hanya menghasilkan penanda dan placeholder:

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

Render sekali sebagai pengunjung anonim dan sekali sebagai pengguna yang masuk, lalu kedua string akan identik hingga tingkat byte. Sifat inilah yang dibutuhkan oleh prarender statis dengan serveLoggedIn aktif: siapa pun yang memicu render, dokumen yang disimpan akan sama dan tidak ada data personal yang dapat masuk ke dalamnya.

Langkah 3: Permintaan fragmen

Runtime mengirim semua pulau yang siap dalam satu permintaan:

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

Respons menggunakan clientId sebagai kunci. Untuk pengunjung yang sudah masuk:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

Entri yang gagal diverifikasi akan menghasilkan kode error, bukan HTML, tanpa menggagalkan seluruh batch. Di sini, entri kedua mengubah guestLabel tanpa tanda tangan yang cocok, dan entri ketiga menyebut block yang bukan pulau dinamis:

JSON
{
    "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"
    }
}

Setiap respons menyertakan Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache, dan X-Robots-Tag: noindex. Endpoint berada di bawah /wp-json, yang selalu dilewati oleh prarender statis. Karena itu, cache origin maupun CDN yang mengikuti header origin tidak akan menyimpan fragmen.

Siapa pengunjungnya

Runtime mengirim permintaan dengan credentials: 'same-origin', sehingga browser menyertakan cookie login WordPress. WordPress REST API biasanya mengabaikan autentikasi cookie tanpa nonce, sedangkan nonce tidak dapat disimpan di halaman yang di-cache. Endpoint pulau menangani hal ini sendiri: untuk permintaan browser dari origin yang sama, endpoint memvalidasi cookie logged_in dan memulihkan pengguna tersebut sebelum merender.

Origin yang sama ditentukan dari header Sec-Fetch-Site dan, jika ada, header Origin yang dibandingkan dengan home_url(). Permintaan dari origin lain yang kebetulan membawa cookie akan dirender sebagai anonim, sehingga permintaan dari situs lain tidak pernah merender fragmen personal pengunjung. Dalam praktiknya:

Permintaan Dirender sebagai
Fetch dari origin yang sama dengan cookie login valid pengguna yang sudah masuk
Permintaan lintas origin dengan cookie yang sama anonim
Tanpa cookie anonim

Halaman Ini yang Mana?

Tambahkan "context": true ke blockstudio.island jika fragmen memerlukan identitas halamannya. Penanda tersebut kemudian menandatangani ID pos dan jenis pos dari halaman yang dikueri bersama atributnya. Di dalam fragmen, $block['postId'], $block['postType'], get_the_ID(), dan get_queried_object_id() merujuk ke halaman tersebut. Di dalam Query Loop, ini tetap berarti halaman luar yang dikueri, bukan item loop.

Konteks halaman bersifat opsional dan juga menjadi bagian dari kunci cache fragmen. Endpoint memeriksa akses kembali, bahkan untuk fragmen yang di-cache, sehingga penanda bertanda tangan tidak membuka halaman yang kemudian menjadi privat atau dilindungi kata sandi. Lihat Konteks Halaman untuk detail konfigurasi dan keamanan. URL atau parameter kueri sembarang tidak diputar ulang.

Langkah 4: Jumlah keranjang yang diperbarui sendiri

Pulau kedua menampilkan gaya placeholder yang lain dan dua opsi runtime. Alih-alih menggunakan file placeholder terpisah, template memeriksa $isIslandPlaceholder:

JSON
{
  "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
<?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; ?>

Flag yang sama tersedia di setiap bahasa template: isIsland, isIslandPlaceholder, isIslandFragment, dan islandPhase ("normal", "hydrate", "placeholder", atau "fragment"). Dalam contoh ini, jumlahnya berasal dari filter acme/cart_count yang nilainya diisi oleh kode commerce Anda; jika filter mengembalikan 3, endpoint akan memberikan:

JSON
{"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" menunda permintaan hingga penanda masuk ke viewport, menggunakan IntersectionObserver. Pulau yang terlihat pada waktu bersamaan tetap digabung dalam satu permintaan. event menentukan nama event window yang mengambil ulang data pulau. Jadi, setelah pemanggilan add-to-cart, skrip Anda hanya perlu memicu event tersebut:

JavaScript
window.dispatchEvent(new Event('acme:cart-updated'));

Merespons dalam kode frontend

Peristiwa merambat dari penanda, jadi satu listener pada document mencakup setiap pulau. event.detail.name menyimpan nama blok:

JavaScript
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);
});

Setelah pertukaran, runtime mengirim blockstudio:island:rendered, lalu blockstudio:island:hydrate. Jika gagal, placeholder tetap di tempatnya dan blockstudio:island:error dijalankan. Pulau yang sudah dihidrasi ("island": "hydrate") sepenuhnya melewati permintaan: seluruh HTML-nya ada di halaman dan hanya menerima peristiwa hydrate, cocok untuk blok interaktif yang aman di-cache seperti tab.

Caching fragmen

Secara default, fragmen dirender pada setiap permintaan. Sapaan di atas memilih cache singkat:

JSON
{
  "cache": {
    "ttl": 300,
    "per": "user"
  }
}

per: "user" membedakan fragmen yang di-cache berdasarkan ID pengguna WordPress, dan permintaan anonim tidak pernah di-cache dengan kunci ini, sehingga dua pengunjung anonim tidak dapat berbagi entri yang ditujukan untuk pengguna tertentu. per: "global" membagikan satu fragmen untuk blok dan atribut yang sama, cocok untuk konten yang terus diperbarui tetapi tidak bersifat pribadi, seperti tingkat stok. ttl menggunakan nilai bawaan 60 detik, dan cache: true adalah cache global 60 detik.

Model keamanan

Endpoint ini bersifat publik, tetapi bukan perender blok umum. Entri hanya dirender jika semua syarat berikut terpenuhi:

  • blok terdaftar, bersifat dinamis, dan island.mode disetel ke dynamic
  • tanda tangan cocok dengan nama blok dan atribut yang lolos filter: hanya kunci yang ada dalam skema blok dan daftar izin pulau

Tanda tangan adalah HMAC-SHA256 atas nama blok dan atribut yang dinormalisasi, dengan salt auth situs yang melayani sebagai kunci. Tanda tangan dibuat saat perenderan di situs tersebut dan tidak pernah disertakan dalam tema. Ada dua konsekuensinya. Dokumen yang dirender di staging membawa tanda tangan staging, jadi render dokumen di situs yang menyajikannya. Dan rotasi salt WordPress membatalkan setiap tanda tangan dalam dokumen tersimpan, jadi hapus hasil prerender statis setelah rotasi salt.

Satu permintaan menerima hingga 50 pulau; jumlah lebih banyak akan mengembalikan HTTP 413. Ubah batas dengan blockstudio/islands/max_per_request. Hook tanda tangan (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) tersedia bagi host yang memerlukan skema berbeda.

Kapan tidak menggunakan pulau

Fragmen tidak ada dalam HTML awal, jadi perayap tidak dapat melihatnya. Simpan konten yang relevan untuk SEO di render normal. Gunakan pulau dinamis untuk konten yang dapat dimuat setelah kerangka halaman: tautan akun, status keranjang, rekomendasi, dan kontrol yang dibatasi izin. Jika seluruh halaman bersifat pribadi, seperti dasbor akun, cantumkan path-nya di dynamicPaths dan render secara langsung.

Langkah berikutnya