Przejdź do treści

Spersonalizowane fragmenty na stronach z pamięci podręcznej

Strona podawana z pamięci podręcznej jest taka sama dla wszystkich. Na tym polega buforowanie, ale właśnie to stanowi problem: nagłówek ma wyświetlać zalogowanemu klientowi powitanie „Cześć, Ada”, a ikona koszyka ma pokazywać trzy produkty. Jeśli szablon rozgałęzia logikę na podstawie bieżącego użytkownika, pamięć podręczna albo zapisze powitanie jednego odwiedzającego dla wszystkich, albo pominie buforowanie całej strony.

Dynamiczne wyspy Blockstudio rozdzielają te dwa problemy. Buforowany HTML zawiera bezpieczny dla pamięci podręcznej symbol zastępczy. Po załadowaniu strony niewielki kod środowiska wykonawczego pobiera od WordPress spersonalizowany fragment w osobnym żądaniu odwiedzającego i wstawia go na miejsce symbolu. Strona pozostaje możliwa do buforowania, a aktualizowany na bieżąco jest tylko fragment.

Ten przewodnik pokazuje, jak utworzyć dwie wyspy: powitanie i licznik koszyka. Wyjaśnia, co zawiera buforowana strona, jak wygląda żądanie fragmentu i jak punkt końcowy ustala tożsamość odwiedzającego. Uzupełnia go przewodnik Udostępnianie WordPress jako statycznej HTML.

Jak działa dynamiczna wyspa

  1. Blok renderuje symbol zastępczy wewnątrz elementu znacznikowego. Znacznik zawiera nazwę bloku, dozwolone atrybuty i podpis wygenerowany przez serwer.
  2. Ponieważ renderowana strona zawiera znacznik, Blockstudio dołącza kod środowiska wykonawczego wyspy. Strony bez wysp nie dostarczają kodu JavaScript wyspy.
  3. Kod środowiska wykonawczego zbiera gotowe znaczniki i wysyła jedno zbiorcze żądanie POST do /wp-json/blockstudio/v1/island/render.
  4. Punkt końcowy weryfikuje każdy podpis, renderuje blok w kontekście żądania odwiedzającego i zwraca fragmenty.
  5. Kod środowiska wykonawczego zastępuje każdy symbol zastępczy i wysyła zdarzenia.

W edytorze bloków blok renderuje się normalnie, bez symbolu zastępczego.

Krok 1: Blok powitania

Utwórz blok z trzema plikami:

Kod
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" sprawia, że jest to wyspa wysyłająca żądanie fragmentu. tag ustawia element znacznikowy, dzięki czemu wyspa może być umieszczona w wierszu paska nawigacyjnego. attributes to lista dozwolonych atrybutów bloku przesyłanych wraz z żądaniem fragmentu; niewymienione atrybuty nie są ani wysyłane, ani podpisywane. Zagadnienie cache omawiamy dalej.

Buforowana strona zawiera symbol zastępczy. Musi on być bezpieczny dla każdego odwiedzającego, więc nie może zawierać żadnych danych użytkownika. Odnośnik „Konto” będzie odpowiedni dla każdego:

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

Główny szablon renderuje właściwy fragment:

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

W tym miejscu można rozgałęziać logikę na podstawie bieżącego użytkownika: ten szablon jest uruchamiany tylko dla żądania fragmentu, nigdy dla buforowanej strony.

Umieść go w miejscu renderowania nagłówka:

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

Działają też tagi bloków: <bs:acme-greeting /> lub <block name="acme/greeting" />.

Krok 2: Zawartość buforowanej strony

Po renderowaniu na serwerze blok tworzy tylko znacznik i symbol zastępczy:

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>

Wykonaj renderowanie raz jako anonimowy odwiedzający, a raz jako zalogowany użytkownik; oba ciągi bajt po bajcie będą identyczne. Tego właśnie wymaga statyczne renderowanie wstępne z włączoną opcją serveLoggedIn: niezależnie od tego, kto je uruchomi, zapisany dokument będzie taki sam i nie trafią do niego żadne dane osobowe.

Krok 3: Żądanie fragmentu

Kod środowiska wykonawczego przesyła wszystkie gotowe wyspy w jednym żądaniu:

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

Odpowiedź jest indeksowana według clientId. W przypadku zalogowanego odwiedzającego:

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

Wpis, który nie przejdzie weryfikacji, zwróci kod błędu zamiast HTML, ale nie spowoduje odrzucenia pozostałych pozycji zbiorczego żądania. W tym przypadku zmieniono guestLabel drugiej pozycji bez odpowiadającego mu podpisu, a trzecia wskazywała blok, który nie jest dynamiczną wyspą:

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

Każda odpowiedź zawiera Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache i X-Robots-Tag: noindex. Punkt końcowy działa pod adresem /wp-json, który statyczne renderowanie wstępne zawsze omija, więc fragmentu nie zapisze ani pamięć podręczna serwera źródłowego, ani CDN respektujący nagłówki serwera źródłowego.

Kim jest odwiedzający

Kod środowiska wykonawczego wysyła żądanie z credentials: 'same-origin', dzięki czemu przeglądarka dołącza plik cookie logowania WordPress. WordPress REST API zwykle ignoruje uwierzytelnianie za pomocą pliku cookie bez tokenu nonce, a token nonce nie może znaleźć się na buforowanej stronie. Punkt końcowy wyspy obsługuje to samodzielnie: w przypadku żądania przeglądarki z tej samej domeny weryfikuje plik cookie logged_in i przywraca użytkownika przed renderowaniem.

Żądanie z tej samej domeny rozpoznaje się na podstawie nagłówka Sec-Fetch-Site i, jeśli występuje, nagłówka Origin porównywanego z home_url(). Żądanie z innego źródła, które przypadkiem zawiera plik cookie, jest renderowane jako anonimowe. Zatem żądanie z innej witryny nigdy nie wygeneruje spersonalizowanego fragmentu odwiedzającego. W praktyce:

Żądanie Renderowanie jako
Żądanie fetch z tej samej domeny z prawidłowym plikiem cookie logowania zalogowany użytkownik
Żądanie z innej domeny z tym samym plikiem cookie anonimowy użytkownik
Brak pliku cookie anonimowy użytkownik

Która to strona?

Dodaj "context": true do blockstudio.island, gdy fragment wymaga identyfikatora swojej strony. Znacznik podpisuje wtedy ID wpisu i typ wpisu odpytywanej strony razem z atrybutami. W tym fragmencie $block['postId'], $block['postType'], get_the_ID() i get_queried_object_id() odnoszą się do tej strony. Wewnątrz pętli Query Loop nadal oznacza to zewnętrzną odpytywaną stronę, a nie element pętli.

Kontekst strony jest opcjonalny i stanowi również część klucza pamięci podręcznej fragmentów. Punkt końcowy ponownie sprawdza dostęp, nawet w przypadku fragmentów z pamięci podręcznej, więc podpisany znacznik nie ujawnia strony, która od tego czasu stała się prywatna lub chroniona hasłem. Szczegóły konfiguracji i zabezpieczeń znajdziesz w sekcji Kontekst strony. Nie są ponownie odtwarzane dowolne URL ani parametry zapytania.

Krok 4: Licznik koszyka, który sam się odświeża

Druga wyspa pokazuje inny styl symbolu zastępczego i dwie opcje środowiska wykonawczego. Zamiast osobnego pliku symbolu zastępczego szablon sprawdza $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; ?>

Te same flagi są dostępne w każdym języku szablonów: isIsland, isIslandPlaceholder, isIslandFragment i islandPhase ("normal", "hydrate", "placeholder" lub "fragment"). W tym przykładzie licznik pobiera wartość z filtra acme/cart_count, który wypełnia kod sklepu. Gdy zwraca on wartość 3, punkt końcowy zwraca:

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" wstrzymuje żądanie do chwili, gdy znacznik znajdzie się w obszarze widoku, korzystając z IntersectionObserver. Widoczne jednocześnie wyspy nadal są łączone w jedno żądanie. event określa zdarzenie okna, które ponownie pobiera wyspę, więc po wywołaniu dodania do koszyka skrypt musi tylko je zasygnalizować:

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

Reakcja w kodzie frontendu

Zdarzenia propagują się od znacznika, więc jeden nasłuchujący na document obsługuje każdą wyspę. event.detail.name przechowuje nazwę bloku:

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

Po podmianie środowisko wykonawcze wywołuje blockstudio:island:rendered, a następnie blockstudio:island:hydrate. W razie niepowodzenia symbol zastępczy pozostaje na miejscu i uruchamia się blockstudio:island:error. Uwodnione wyspy ("island": "hydrate") całkowicie pomijają żądanie: cały ich HTML znajduje się na stronie i otrzymują tylko zdarzenie hydrate, co sprawdza się w przypadku bloków interaktywnych bezpiecznych dla pamięci podręcznej, takich jak karty.

Buforowanie fragmentów

Domyślnie fragmenty są renderowane przy każdym żądaniu. Powyższe powitanie korzysta z krótkiego buforowania:

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

per: "user" różnicuje buforowany fragment według identyfikatora użytkownika WordPress, a żądania anonimowe nigdy nie są w ten sposób buforowane, więc dwoje anonimowych odwiedzających nie może współdzielić wpisu przeznaczonego dla jednego użytkownika. per: "global" udostępnia jeden fragment dla tego samego bloku i atrybutów, co sprawdza się w przypadku aktualizowanych na bieżąco, ale nieosobistych treści, takich jak stan magazynowy. ttl domyślnie wynosi 60 sekund, a cache: true to globalna pamięć podręczna z czasem 60 sekund.

Model bezpieczeństwa

Punkt końcowy jest publiczny, ale nie renderuje dowolnych bloków. Renderuje wpis tylko wtedy, gdy spełnione są wszystkie poniższe warunki:

  • blok jest zarejestrowany, dynamiczny, a dla island.mode ustawiono wartość dynamic
  • podpis pasuje do nazwy bloku i atrybutów, które przeszły filtr: uwzględniane są tylko klucze występujące zarówno w schemacie bloku, jak i na liście dozwolonych kluczy wyspy

Podpis jest skrótem HMAC-SHA256 obliczonym na podstawie znormalizowanej nazwy bloku i atrybutów, z użyciem soli auth witryny obsługującej żądanie. Podpisy są tworzone podczas renderowania w tej witrynie i nigdy nie są osadzane w motywie. Wynikają z tego dwie rzeczy. Dokument wyrenderowany w środowisku testowym zawiera podpisy z tego środowiska, dlatego renderuj dokumenty w witrynie, która je udostępnia. Zmiana soli WordPress unieważnia wszystkie podpisy w zapisanych dokumentach, dlatego po zmianie soli wyczyść statycznie wygenerowane strony.

Jedno żądanie obsługuje maksymalnie 50 wysp; większa liczba zwraca HTTP 413. Zmień limit za pomocą blockstudio/islands/max_per_request. Haki podpisu (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) są dostępne dla hostów, które potrzebują innego mechanizmu.

Kiedy nie używać wyspy

Fragmentów nie ma w początkowym HTML, więc roboty indeksujące ich nie widzą. Treści istotne dla SEO umieszczaj w standardowym renderowaniu. Używaj dynamicznych wysp dla elementów, które mogą pojawić się po załadowaniu szkieletu strony: linków do konta, stanu koszyka, rekomendacji i kontrolek dostępnych po uzyskaniu uprawnień. Jeśli cała strona jest spersonalizowana, jak panel konta, zamiast tego dodaj jej ścieżkę do dynamicPaths i renderuj ją na bieżąco.

Następne kroki