Перейти до вмісту

Персоналізовані фрагменти на кешованих сторінках

Сторінка зі статичного кешу однакова для всіх. У цьому й сенс кешування, але в цьому ж і проблема: у заголовку хочеться написати «Привіт, Ada» для клієнта, який увійшов у систему, а біля значка кошика показати три товари. Якщо шаблон перевіряє поточного користувача, кеш або зберігає привітання одного відвідувача для всіх, або сторінку взагалі доводиться виключити з кешу.

Динамічні острівці Blockstudio розділяють ці два завдання. Кешований HTML містить безпечну для кешування заглушку. Після завантаження сторінки невелике середовище виконання запитує в WordPress персональний фрагмент у межах власного запиту відвідувача й підставляє його. Сторінка залишається придатною для кешування, а динамічним є лише фрагмент.

У цьому посібнику створюються два острівці — привітання та лічильник кошика — і пояснюється, що містить кешована сторінка, як виглядає запит фрагмента та як кінцева точка визначає особу відвідувача. Посібник доповнює матеріал Створення статичного WordPressз HTML.

Як працює динамічний острівець

  1. Блок рендерить заглушку всередині елемента-маркера. Маркер містить назву блока, дозволені атрибути та підпис, створений сервером.
  2. Оскільки відрендерена сторінка містить маркер, Blockstudio підключає середовище виконання острівців. Сторінки без острівців не завантажують їхнє JavaScript.
  3. Середовище виконання збирає готові маркери й надсилає один пакетний POST до /wp-json/blockstudio/v1/island/render.
  4. Кінцева точка перевіряє кожен підпис, рендерить блок у контексті запиту відвідувача й повертає фрагменти.
  5. Середовище виконання замінює кожну заглушку й надсилає події.

У редакторі блоків блок рендериться звичайно, без заглушки.

Крок 1: блок привітання

Створіть блок із трьох файлів:

Код
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" перетворює його на острівець із запитом фрагмента. tag задає елемент-маркер, тож острівець може розташовуватися в рядку панелі навігації. attributes — це список дозволених атрибутів блока, які передаються разом із запитом фрагмента; усе, що до нього не внесено, не надсилається й не підписується. cache розглянуто далі.

Кешована сторінка містить заглушку. Вона має бути безпечною для показу всім відвідувачам, тому не містить даних користувача. Посилання «Обліковий запис» підійде для всіх:

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

Основний шаблон рендерить справжній фрагмент:

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

У цьому разі можна перевіряти поточного користувача: цей шаблон запускається лише для запиту фрагмента, а не для кешованої сторінки.

Розмістіть його там, де рендериться заголовок:

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

Можна використовувати й теги блока: <bs:acme-greeting /> або <block name="acme/greeting" />.

Крок 2: вміст кешованої сторінки

Під час рендерингу на сервері блок створює лише маркер і заглушку:

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>

Відрендерте її один раз як анонімний відвідувач, а потім — як користувач, що ввійшов у систему: обидва рядки будуть ідентичними до байта. Саме така властивість потрібна статичному попередньому рендерингу з увімкненим serveLoggedIn: хто б не запустив рендеринг, збережений документ буде однаковим, і в нього не потраплять персональні дані.

Крок 3: запит фрагмента

Середовище виконання надсилає всі готові острівці одним запитом:

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

Відповідь містить ключі clientId. Для відвідувача, який увійшов у систему:

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

Для запису, який не пройшов перевірку, повертається код помилки замість HTML; це не заважає обробити решту пакетного запиту. Тут у другому записі змінили guestLabel без відповідного підпису, а в третьому вказали блок, який не є динамічним острівцем:

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

Кожна відповідь містить Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache та X-Robots-Tag: noindex. Кінцева точка розташована за адресою /wp-json, яку статичний попередній рендеринг завжди оминає. Тому ані кеш джерела, ані CDN, який враховує заголовки джерела, не збереже фрагмент.

Як визначається відвідувач

Середовище виконання надсилає запит із credentials: 'same-origin', тому браузер додає файл cookie входу WordPress. WordPress REST API зазвичай ігнорує автентифікацію за файлом cookie без nonce, а nonce не можна розмістити на кешованій сторінці. Кінцева точка острівців виконує перевірку самостійно: для браузерного запиту з того самого джерела вона перевіряє файл cookie logged_in і відновлює дані користувача перед рендерингом.

Належність до того самого джерела визначається за заголовком Sec-Fetch-Site і, якщо він є, заголовком Origin, який порівнюється з home_url(). Запит з іншого джерела, навіть якщо він містить цей файл cookie, обробляється як анонімний. Тож запит із іншого сайту ніколи не рендерить персональний фрагмент відвідувача. На практиці:

Запит Відображається як
Запит fetch з того самого джерела з чинним файлом cookie входу користувач, який увійшов у систему
Запит з іншого джерела з тим самим файлом cookie анонімний відвідувач
Немає файла cookie анонімний відвідувач

Яка це сторінка?

Додайте "context": true до blockstudio.island, якщо фрагменту потрібна ідентичність його сторінки. Тоді маркер підписує ідентифікатор допису та тип допису запитаної сторінки разом з атрибутами. У фрагменті $block['postId'], $block['postType'], get_the_ID() і get_queried_object_id() посилаються на цю сторінку. Усередині циклу запитів це все ще зовнішня запитана сторінка, а не елемент циклу.

Контекст сторінки вмикається за бажанням і також входить до ключа кешу фрагментів. Кінцева точка повторно перевіряє доступ навіть для кешованих фрагментів, тож підписаний маркер не відкриє сторінку, яка згодом стала приватною або захищеною паролем. Див. Контекст сторінки, щоб дізнатися про налаштування та безпеку. Довільні URL чи параметри запиту не відтворюються.

Крок 4: лічильник кошика, який оновлюється сам

Другий острівець демонструє інший стиль заглушки та два параметри середовища виконання. Замість окремого файла заглушки шаблон перевіряє $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; ?>

Ті самі прапорці доступні в усіх мовах шаблонів: isIsland, isIslandPlaceholder, isIslandFragment та islandPhase ("normal", "hydrate", "placeholder" або "fragment"). Тут кількість надходить із фільтра acme/cart_count, значення якого надає ваш код електронної комерції. Якщо він повертає 3, кінцева точка повертає:

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" відкладає запит, доки маркер не з’явиться в області перегляду, використовуючи IntersectionObserver. Видимі острівці, що з’являються одночасно, усе одно об’єднуються в один запит. event задає назву події вікна, яка повторно запитує острівець. Тож після виклику додавання товару до кошика ваш скрипт має лише повідомити про нього:

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

Реагування у фронтенд-коді

Події спливають від маркера, тож одного обробника на document достатньо для кожного острова. event.detail.name містить назву блока:

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

Після заміни середовище виконання надсилає blockstudio:island:rendered, а потім blockstudio:island:hydrate. У разі помилки заповнювач залишається на місці й спрацьовує blockstudio:island:error. Гідратовані острови ("island": "hydrate") повністю пропускають запит: увесь їхній HTML уже є на сторінці, і вони отримують лише подію hydrate, що добре підходить для інтерактивних блоків із безпечним кешуванням, як-от вкладки.

Кешування фрагментів

За замовчуванням фрагменти рендеряться під час кожного запиту. Привітання вище використовує короткий кеш:

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

per: "user" розділяє кешовані фрагменти за ID WordPress користувача; анонімні запити за цим ключем ніколи не кешуються, тож два анонімні відвідувачі не можуть спільно використовувати запис, призначений для користувача. per: "global" використовує один фрагмент для однакового блока й атрибутів, що підходить для актуального, але неперсонального вмісту, наприклад рівня запасів. ttl за замовчуванням дорівнює 60 секундам, а cache: true — це глобальний кеш на 60 секунд.

Модель безпеки

Ендпоінт загальнодоступний, але це не універсальний рендерер блоків. Він рендерить запис, лише якщо виконуються всі умови:

  • блок зареєстрований, є динамічним і для island.mode встановлено значення dynamic
  • підпис відповідає назві блока й атрибутам, що пройшли фільтр: лише ключам, наявним і в схемі блока, і в списку дозволених острова

Підпис — це HMAC-SHA256 для нормалізованої назви блока й атрибутів, створений із використанням солі auth сайту, що обслуговує запит. Підписи створюються під час рендерингу на цьому сайті й ніколи не вбудовуються в тему. Звідси випливають два наслідки. Документ, відрендерений на тестовому середовищі, містить підписи цього середовища, тож рендерте документи на сайті, який їх обслуговує. А зміна солей WordPress робить недійсними всі підписи в збережених документах, тому після зміни солі очистьте статичний попередній рендеринг.

Один запит приймає до 50 островів; більша кількість повертає HTTP 413. Змініть ліміт за допомогою blockstudio/islands/max_per_request. Хуки підпису (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) доступні для хостів, яким потрібна інша схема.

Коли не варто використовувати острів

Фрагменти відсутні в початковому HTML, тому сканери їх не бачать. Вміст, важливий для SEO, залишайте у звичайному рендерингу. Використовуйте динамічні острови для того, що може з’явитися після оболонки сторінки: посилань на обліковий запис, стану кошика, рекомендацій і елементів керування з обмеженим доступом. Якщо вся сторінка персональна, як-от панель облікового запису, натомість укажіть її шлях у dynamicPaths і рендерте сторінку наживо.

Наступні кроки