캐시된 페이지의 개인화된 조각
정적 캐시에서 제공되는 페이지는 누구에게나 동일합니다. 캐시의 목적이 바로 그것이지만, 동시에 문제가 되기도 합니다. 헤더에는 로그인한 고객에게 “안녕하세요, Ada”라고 표시하고 장바구니 아이콘에는 상품 세 개를 표시하고 싶을 수 있습니다. 템플릿에서 현재 사용자에 따라 분기하면 캐시에 한 방문자의 인사말이 모두에게 제공되거나 페이지 전체를 캐시에서 제외해야 합니다.
Blockstudio의 동적 아일랜드는 이 두 가지 요구를 분리합니다. 캐시된 HTML에는 캐시에 안전한 자리표시자가 들어갑니다. 페이지가 로드된 후 작은 런타임이 방문자 자신의 요청으로 WordPress에 개인화된 조각을 요청해 해당 위치에 삽입합니다. 페이지는 계속 캐시할 수 있고 조각만 실시간으로 제공됩니다.
이 가이드에서는 인사말과 장바구니 개수라는 두 아일랜드를 만들고, 캐시된 페이지에 어떤 내용이 들어가는지, 조각 요청은 어떤 형태인지, 엔드포인트가 방문자를 어떻게 식별하는지 살펴봅니다. 정적으로 제공WordPress하기HTML 가이드와 함께 읽으면 좋습니다.
동적 아일랜드의 작동 방식
- 블록은 마커 요소 안에 자리표시자를 렌더링합니다. 마커에는 블록 이름, 허용 목록에 포함된 속성, 서버에서 생성한 서명이 들어갑니다.
- 렌더링된 페이지에 마커가 있으므로 Blockstudio가 아일랜드 런타임을 삽입합니다. 아일랜드가 없는 페이지에는 아일랜드 JavaScript가 포함되지 않습니다.
- 런타임이 준비된 마커를 모아 하나의 묶음
POST를/wp-json/blockstudio/v1/island/render로 전송합니다. - 엔드포인트는 각 서명을 확인하고 방문자의 요청 컨텍스트에서 블록을 렌더링한 뒤 조각을 반환합니다.
- 런타임은 각 자리표시자를 바꾸고 이벤트를 디스패치합니다.
블록 편집기에서는 자리표시자 없이 블록이 정상적으로 렌더링됩니다.
1단계: 인사말 블록
다음 세 파일로 블록을 만듭니다:
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>
익명 방문자와 로그인한 사용자로 각각 한 번씩 렌더링해 두 문자열이 바이트 단위까지 일치하는지 확인합니다. 정적 사전 렌더링에 serveLoggedIn를 활성화할 때 필요한 속성입니다. 누가 렌더링을 시작하든 저장되는 문서는 동일하며 개인 정보가 문서에 포함되지 않습니다.
3단계: 조각 요청
런타임은 준비된 모든 아일랜드를 한 번의 요청으로 전송합니다:
{
"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 대신 오류 코드로 반환됩니다. 여기서는 두 번째 항목이 일치하는 서명 없이 guestLabel를 변경했고, 세 번째 항목은 동적 아일랜드가 아닌 블록을 지정했습니다:
{
"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 로그인 쿠키가 포함됩니다. WordPress REST API는 일반적으로 nonce가 없으면 쿠키 인증을 무시하며, 캐시된 페이지에는 nonce를 넣을 수 없습니다. 아일랜드 엔드포인트가 직접 이를 처리합니다. 동일 출처 브라우저 요청이면 logged_in 쿠키를 검증하고 렌더링 전에 해당 사용자 정보를 복원합니다.
동일 출처 여부는 Sec-Fetch-Site 헤더를 기준으로 판단하며, Origin 헤더가 있으면 이를 home_url()와 비교합니다. 쿠키가 포함되어 있어도 다른 출처에서 온 요청은 익명으로 렌더링되므로 다른 사이트에서 방문자의 개인 조각을 렌더링할 수 없습니다. 실제 동작은 다음과 같습니다:
| 요청 | 렌더링 결과 |
|---|---|
| 유효한 로그인 쿠키를 포함한 동일 출처 fetch | 로그인한 사용자 |
| 같은 쿠키를 포함한 교차 출처 요청 | 익명 |
| 쿠키 없음 | 익명 |
이 페이지는 무엇인가요?
조각에 해당 페이지의 정체성이 필요하면 blockstudio.island에 "context": true을 추가하세요. 그러면 마커가 속성과 함께 조회된 페이지의 게시물 ID와 게시물 유형에 서명합니다. 조각 안에서 $block['postId'], $block['postType'], get_the_ID(), get_queried_object_id()는 해당 페이지를 가리킵니다. Query Loop 안에서도 루프 항목이 아니라 바깥쪽에서 조회한 페이지를 의미합니다.
페이지 컨텍스트는 선택적으로 활성화되며 조각 캐시 키에도 포함됩니다. 엔드포인트는 캐시된 조각도 포함해 접근 권한을 다시 확인하므로, 서명된 마커가 이후 비공개 또는 비밀번호 보호 상태로 바뀐 페이지를 노출하지 않습니다. 구성 및 보안 세부 정보는 페이지 컨텍스트를 참조하세요. 임의의 URL나 쿼리 매개변수는 재생되지 않습니다.
4단계: 자동으로 새로 고쳐지는 장바구니 개수
두 번째 아일랜드에서는 다른 자리표시자 스타일과 두 가지 런타임 옵션을 보여줍니다. 별도의 자리표시자 파일을 사용하는 대신 템플릿에서 $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를 사용해 마커가 뷰포트에 들어올 때까지 요청을 미룹니다. 동시에 표시되는 아일랜드는 여전히 하나의 요청으로 묶입니다. event는 아일랜드를 다시 가져오는 윈도우 이벤트의 이름입니다. 따라서 장바구니 담기 요청 후 스크립트에서 해당 이벤트를 알리기만 하면 됩니다:
window.dispatchEvent(new Event('acme:cart-updated'));
프런트엔드 코드에서 반응하기
이벤트는 마커에서 버블링되므로 document에 리스너 하나만 등록하면 모든 아일랜드를 처리할 수 있습니다. 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 솔트를 키로 사용합니다. 서명은 해당 사이트에서 렌더링할 때 생성되며 테마에 포함되지 않습니다. 이에 따라 두 가지 결과가 생깁니다. 스테이징에서 렌더링한 문서에는 스테이징 서명이 포함되므로 문서를 제공하는 사이트에서 렌더링해야 합니다. 또한 WordPress 솔트를 변경하면 저장된 문서의 모든 서명이 무효화되므로, 솔트 변경 후 정적 사전 렌더링 결과를 삭제해야 합니다.
요청 하나당 아일랜드를 최대 50개까지 처리할 수 있으며, 초과하면 HTTP 413가 반환됩니다. blockstudio/islands/max_per_request로 제한을 변경할 수 있습니다. 다른 방식을 써야 하는 호스트를 위해 서명 후크(blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature)가 제공됩니다.
아일랜드를 사용하지 말아야 할 때
프래그먼트는 최초 HTML에 포함되지 않으므로 크롤러가 이를 볼 수 없습니다. SEO 관련 콘텐츠는 일반 렌더링에 포함하세요. 페이지 셸이 로드된 뒤 표시해도 되는 계정 링크, 장바구니 상태, 추천, 권한 제한 컨트롤에는 동적 아일랜드를 사용하세요. 계정 대시보드처럼 페이지 전체가 개인화된 경우에는 그 경로를 dynamicPaths에 나열하고 실시간으로 렌더링하세요.
다음 단계
- 아일랜드 레퍼런스: 모든 옵션, 플레이스홀더 조회 순서, PHP API 및 후크
- 정적 WordPress 제공하기HTML: 이 아일랜드가 사용하도록 설계된 캐시
- 정적 사전 렌더링 레퍼런스:
serveLoggedIn, 동적 경로 및 조기 제공 - 대화형 컴포넌트: 마운트 이벤트 이상의 동작이 필요한 블록의 클라이언트 동작