커스텀 통합

개요

Aftersell의 기본 노출 영역(구매 후, 체크아웃, Upcart)이나 패키지형 통합이 모두 맞지 않을 때는, Shopify 테마에서 Strategies API를 직접 호출하고 반환된 상품을 원하는 방식으로 렌더링할 수 있어요. 패턴은 모든 경우에 동일해요: Liquid로 컨텍스트 페이로드를 구성하고(현재 상품, 카트 내용, 고객 필드 같은 Shopify 속성이 렌더링 시점에 채워지도록), /api/public/strategy/evaluate에 POST한 뒤 응답을 렌더링해요. 이 페이지에서는 두 가지 구현 패턴을 다뤄요:

PDP 컨텍스트 - 상품 페이지에 섹션을 배치하여 현재 보고 있는 상품으로 API를 호출하고 반환된 추천 상품의 캐러셀을 렌더링해요.
카트 컨텍스트 - 커스텀 카트 안에 업셀 블록을 렌더링하여 현재 카트의 모든 라인 아이템으로 API를 호출하고 반환된 상품을 렌더링해요.

두 패턴의 차이는 상품 컨텍스트의 형태예요: PDP에서는 단일 상품, 카트에서는 모든 라인 아이템의 배열이에요.

필요한 것

Strategy API 키. Aftersell에서 Settings → Product Strategy로 이동한 뒤 Security Token 카드에서 토큰을 복사하세요 (이것이 Strategy API 키예요).
Strategy ID. Aftersell Strategy 편집기에서 실행할 Strategy를 열고 ID를 복사하세요.
테마 코드 접근 권한. Shopify 테마에 Liquid 섹션(PDP) 또는 블록(커스텀 카트)을 추가하게 돼요 - Online Store → Themes → … → Edit code.

Strategy API 키는 클라이언트 측 테마 코드에 포함되므로 페이지 소스를 보는 누구에게나 노출돼요. 공개 스토어프런트 자격 증명으로 취급하고, 의도치 않게 노출된 경우 Aftersell Settings → Product Strategy에서 교체하세요.

PDP 컨텍스트: 섹션 스니펫

이 패턴은 상품 페이지에 Shopify 섹션을 추가해요. 페이지가 렌더링될 때 Liquid가 현재 상품, 카트, 고객 속성을 페이로드에 삽입하고, JavaScript가 Strategies API에 요청을 보내 반환된 상품을 Splide 캐러셀로 렌더링해요.

설치하기

Shopify 관리자에서 Online Store → Themes로 이동하고, 테마에서 **…**를 클릭한 다음 Edit code를 선택하세요.
Sections 폴더 아래에 aftersell-upsell-carousel.liquid라는 새 파일을 만드세요.
아래 스니펫을 새 파일에 붙여넣고 YOUR_STRATEGY_API_KEY를 Aftersell의 API 키로 교체하세요.
저장하세요.
상품 템플릿(일반적으로 templates/product.json 또는 sections/main-product.liquid)을 열고 캐러셀을 표시할 위치에 Aftersell Carousel 섹션을 추가하세요. 테마 편집기에서 상품 페이지로 직접 드래그할 수도 있어요.
섹션 설정에 Strategy ID를 붙여넣으세요.

섹션이 전송하는 것

각 PDP 조회마다 페이로드에는 다음이 포함돼요:

products - 현재 보고 있는 상품이 담긴 단일 요소 배열 (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
cart - 쇼핑객의 현재 카트의 소계, 아이템 수, 라인 수 (카트가 비어 있으면 생략).
cartToken - API가 이 평가를 동일한 세션에 연결할 수 있도록.
customer - 태그, 국가, 지역, 로케일, 주문 수, 총 지출액, 마케팅 수신 동의 플래그, 단 쇼핑객이 로그인한 경우에만.
session - shop.currency의 통화 코드.

이 섹션은 기본적으로 UTM 매개변수를 전송하지 않아요. PDP에서 UTM 기반 타기팅을 원한다면 클라이언트 측에서 캡처하여 fetch 전에 session 객체에 추가하세요.

스니펫

{% comment %}
  Aftersell Carousel (Splide)
  Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}

{% if product %}

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/css/splide-core.min.css">
<script src="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/js/splide.min.js" defer></script>

<div id="aftersell-upsell-{{ section.id }}" class="aftersell-upsell-carousel" style="display:none" {{ section.shopify_attributes }}>
  <h2 class="aftersell-heading">{{ section.settings.heading | default: 'You might also like' }}</h2>
  <div class="aftersell-carousel-wrapper">
    <button class="aftersell-arrow aftersell-arrow--prev" aria-label="Previous" disabled>&#8592;</button>
    <div class="aftersell-track-container">
      <div class="splide" id="aftersell-splide-{{ section.id }}">
        <div class="splide__track">
          <ul class="splide__list">
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
          </ul>
        </div>
      </div>
    </div>
    <button class="aftersell-arrow aftersell-arrow--next" aria-label="Next" disabled>&#8594;</button>
  </div>
</div>

<style>
.aftersell-upsell-carousel { font-family: Modernist, sans-serif; max-width: 1300px; margin: 0 auto; padding: 24px 0 0; box-sizing: border-box; }
.aftersell-heading { font-family: Modernist, sans-serif; font-size: 30px; font-weight: 700; line-height: 45px; color: #0C0A09; margin: 0; }
.aftersell-carousel-wrapper { display: flex; align-items: center; gap: 8px; }
.aftersell-track-container { overflow: hidden; flex: 1; min-width: 0; }
.aftersell-card { display: flex; flex-direction: column; box-sizing: border-box; height: 100%; }
.aftersell-card-link { text-decoration: none; color: inherit; display: block; flex: 1; }
.aftersell-card-image { aspect-ratio: 1; overflow: hidden; background: #f5f5f5; border-radius: 8px 8px 0 0; position: relative; }
.aftersell-card-image img { width: 100%; height: 100%; object-fit: cover; display: block; transition: transform 0.3s ease; }
.aftersell-card-image:hover img { transform: scale(1.04); }
.aftersell-card-badge { position: absolute; top: 10px; left: 8px; background: #c60006; color: #fff; font-size: 11px; font-weight: 500; padding: 4px 8px; border-radius: 16px; z-index: 1; }
.aftersell-card-body { padding: 6px 0 0; display: flex; flex-direction: column; }
.aftersell-card-vendor { font-size: 13px; font-weight: 550; text-transform: uppercase; color: #1d4481; margin: 0; }
.aftersell-card-title { font-size: 13px; font-weight: 700; color: #0C0A09; margin: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.aftersell-card-price { font-size: 13px; color: #0C0A09; margin: 0; display: flex; gap: 6px; align-items: center; flex-wrap: wrap; }
.aftersell-card-price--compare { text-decoration: line-through; color: #595959; }
.aftersell-card-price--sale { font-weight: 700; color: #c60006; }
.aftersell-card-actions { padding: 6px 0 0; display: flex; flex-direction: column; margin-top: auto; }
.aftersell-variant-select { width: 100%; font-size: 13px; padding: 0.35rem 0.5rem; border: 1px solid #DBDBDB; border-radius: 4px; background: #fff; color: #0C0A09; cursor: pointer; }
.aftersell-cta { padding: 16px 12px; background: #c50007; color: #FFFFFF; border: none; border-radius: 5px; font-size: 16px; font-weight: 700; cursor: pointer; width: 100%; display: flex; align-items: center; justify-content: center; transition: background 0.2s, opacity 0.2s; }
.aftersell-cta:hover:not(:disabled) { opacity: 0.85; }
.aftersell-cta:disabled { opacity: 0.5; cursor: default; }
.aftersell-cta--added { background: #1d4481; }
.aftersell-cta--unavailable { background: #999; cursor: default; }
.aftersell-arrow { width: 30px; height: 90px; background: rgba(255,255,255,0.6); border: 1px solid #DBDBDB; border-radius: 5px; cursor: pointer; display: flex; align-items: center; justify-content: center; flex-shrink: 0; padding: 0; }
.aftersell-arrow:disabled { opacity: 0.3; cursor: default; }
.aftersell-skeleton { border-radius: 8px; background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%); background-size: 200% 100%; animation: aftersell-shimmer 1.4s infinite; aspect-ratio: 0.75; width: 100%; }
@keyframes aftersell-shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }

#aftersell-splide-{{ section.id }} .splide__arrows,
#aftersell-splide-{{ section.id }} .splide__pagination { display: none !important; }

@media (max-width: 768px) {
  .aftersell-upsell-carousel { padding: 16px 16px 0; }
  .aftersell-arrow { display: none; }
  .aftersell-carousel-wrapper { gap: 0; }
}
</style>

<script>
(function() {
  var BACKEND_URL  = 'https://start.aftersell.app';
  var API_KEY      = 'YOUR_STRATEGY_API_KEY';
  var STRATEGY_ID  = {{ section.settings.strategy_id | json }};
  var SHOP_DOMAIN  = {{ shop.permanent_domain | json }};
  var CTA_LABEL    = '{{ section.settings.cta_label | default: "Add to cart" }}';
  var MAX_PRODUCTS = {{ section.settings.max_products | default: 8 }};
  var CURRENCY     = {{ shop.currency | default: "USD" | json }};
  var SECTION_ID   = {{ section.id | json }};
  if (!SHOP_DOMAIN || !STRATEGY_ID) return;

  var fmt;
  try {
    fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: CURRENCY });
  } catch(e) {
    fmt = { format: function(n) { return '$' + parseFloat(n).toFixed(2); } };
  }
  function money(str) { return fmt.format(parseFloat(str) || 0); }

  function gidToNumeric(gid) {
    return gid ? String(gid).split('/').pop() : null;
  }

  function priceHtml(price, compareAt) {
    var hasSale = compareAt && parseFloat(compareAt) > parseFloat(price);
    return hasSale
      ? '<span class="aftersell-card-price--compare">' + money(compareAt) + '</span>'
        + '<span class="aftersell-card-price--sale">' + money(price) + '</span>'
      : '<span class="aftersell-card-price--current">' + money(price) + '</span>';
  }

  var productContext = {
    productId:   'gid://shopify/Product/{{ product.id }}',
    variantId:   'gid://shopify/ProductVariant/{{ product.selected_or_first_available_variant.id }}',
    quantity:    1,
    price:       {{ product.price | divided_by: 100.0 }},
    handle:      {{ product.handle | json }},
    title:       {{ product.title | json }},
    vendor:      {{ product.vendor | json }},
    productType: {{ product.type | json }},
    tags:        {{ product.tags | json }},
    collections: [{% for col in product.collections %}'gid://shopify/Collection/{{ col.id }}'{% unless forloop.last %},{% endunless %}{% endfor %}],
    sellingPlan: {% if product.selected_selling_plan %}'subscription'{% else %}'one-time'{% endif %}
  };

  var cartContext = {
    subtotal:  {{ cart.total_price | divided_by: 100.0 }},
    itemCount: {{ cart.item_count }},
    lineCount: {{ cart.items.size }}
  };

  {% if customer %}
  var customerContext = {
    customerId:       'gid://shopify/Customer/{{ customer.id }}',
    tags:             {{ customer.tags | json }},
    {% if customer.default_address.country_code %}countryCode: {{ customer.default_address.country_code | json }},{% endif %}
    {% if customer.default_address.province_code %}provinceCode: {{ customer.default_address.province_code | json }},{% endif %}
    locale:           {{ request.locale.iso_code | json }},
    orderCount:       {{ customer.orders_count }},
    totalSpent:       {{ customer.total_spent | times: 1.0 }},
    acceptsMarketing: {{ customer.accepts_marketing }}
  };
  {% endif %}

  var blockEl  = document.getElementById('aftersell-upsell-' + SECTION_ID);
  var splideEl = document.getElementById('aftersell-splide-' + SECTION_ID);
  var list     = splideEl.querySelector('.splide__list');
  var prevBtn  = blockEl.querySelector('.aftersell-arrow--prev');
  var nextBtn  = blockEl.querySelector('.aftersell-arrow--next');
  var splideInstance = null;

  function getCartToken() {
    var t = {{ cart.token | json }};
    if (t) return Promise.resolve(t);
    return fetch('/cart.js').then(function(r){ return r.json(); }).then(function(c){ return c.token || null; }).catch(function(){ return null; });
  }

  function evaluate() {
    getCartToken().then(function(cartToken) {
      if (!cartToken) return;
      return fetch(BACKEND_URL + '/api/public/strategy/evaluate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'X-Strategy-Api-Key': API_KEY },
        body: JSON.stringify({
          shopDomain:  SHOP_DOMAIN,
          strategyId:  STRATEGY_ID,
          context: {
            products:  [productContext],
            cartToken: cartToken,
            cart:      cartContext.itemCount > 0 ? cartContext : undefined,
            {% if customer %}customer: customerContext,{% endif %}
            session:   { currencyCode: CURRENCY }
          }
        })
      });
    }).then(function(res) { if (!res) return; return res.json(); })
    .then(function(data) {
      if (!data || !data.success || !data.products || !data.products.length) {
        clearSkeletons(); return;
      }
      renderCards(data.products.slice(0, MAX_PRODUCTS));
    }).catch(function(err) {
      console.error('[AfterSell carousel] Error:', err);
      clearSkeletons();
    });
  }

  function renderCards(products) {
    if (!products || !products.length) {
      blockEl.style.display = 'none'; return;
    }

    blockEl.style.display = '';

    list.innerHTML = products.map(function(p, i) {
      var img      = p.images && p.images[0] ? p.images[0].src : '';
      var alt      = (p.images && p.images[0] && p.images[0].altText) || p.title;
      var variants = p.variants || [];
      var availableVariants = variants.filter(function(v) {
        return v.availableForSale !== false;
      });
      var isDefaultVariant = variants.length === 1 && variants[0].title === 'Default Title';
      var showSelect       = !isDefaultVariant && availableVariants.length >= 1;
      var firstVariant     = availableVariants.length ? availableVariants[0] : null;
      var firstVariantId   = firstVariant ? gidToNumeric(firstVariant.variantId) : null;
      var anyAvailable     = availableVariants.length > 0;

      var onSale = p.compareAtPrice && parseFloat(p.compareAtPrice) > parseFloat(p.price);
      var badge  = '';
      if (onSale) {
        var pct = Math.round((1 - parseFloat(p.price) / parseFloat(p.compareAtPrice)) * 100);
        badge = '<span class="aftersell-card-badge">Save ' + pct + '%</span>';
      }
      var vendor = p.vendor ? '<p class="aftersell-card-vendor">' + p.vendor + '</p>' : '';

      var selectHtml = '';
      if (showSelect) {
        var options = availableVariants.map(function(v) {
          return '<option value="' + gidToNumeric(v.variantId) + '"'
            + ' data-price="'   + (v.price         || p.price) + '"'
            + ' data-compare="' + (v.compareAtPrice || '')     + '"'
            + '>' + v.title + '</option>';
        }).join('');
        selectHtml = '<select class="aftersell-variant-select" aria-label="Select variant">' + options + '</select>';
      }

      var atcLabel = anyAvailable ? CTA_LABEL : 'Sold Out';
      var atcClass = anyAvailable ? 'aftersell-cta' : 'aftersell-cta aftersell-cta--unavailable';
      var atcBtn   = '<button class="' + atcClass + '"'
        + (firstVariantId ? ' data-variant-id="' + firstVariantId + '"' : '')
        + (anyAvailable ? '' : ' disabled')
        + '>' + atcLabel + '</button>';

      var productUrl = p.url + (p.url.indexOf('?') > -1 ? '&' : '?') + 'ref=aftersell';

      return '<li class="splide__slide">'
        + '<div class="aftersell-card" data-idx="' + i + '">'
        + '<a class="aftersell-card-link" href="' + productUrl + '">'
        + '<div class="aftersell-card-image">' + badge
        + (img ? '<img src="' + img + '" alt="' + alt + '" loading="lazy">' : '')
        + '</div>'
        + '<div class="aftersell-card-body">'
        + vendor
        + '<p class="aftersell-card-title">' + p.title + '</p>'
        + '<p class="aftersell-card-price" data-price-el>' + priceHtml(p.price, p.compareAtPrice) + '</p>'
        + '</div></a>'
        + '<div class="aftersell-card-actions">'
        + selectHtml
        + atcBtn
        + '</div></div></li>';
    }).join('');

    attachCardEvents();
    initSplide();
  }

  function attachCardEvents() {
    list.addEventListener('change', function(e) {
      if (!e.target.classList.contains('aftersell-variant-select')) return;
      var select  = e.target;
      var card    = select.closest('.aftersell-card');
      var opt     = select.options[select.selectedIndex];
      var priceEl = card.querySelector('[data-price-el]');
      var btn     = card.querySelector('.aftersell-cta');
      priceEl.innerHTML     = priceHtml(opt.getAttribute('data-price'), opt.getAttribute('data-compare'));
      btn.dataset.variantId = opt.value;
      btn.disabled          = false;
      btn.textContent       = CTA_LABEL;
      btn.className         = 'aftersell-cta';
    });

    list.addEventListener('click', function(e) {
      var btn = e.target.closest('.aftersell-cta');
      if (!btn || btn.disabled) return;
      var variantId = btn.dataset.variantId;
      if (!variantId) return;

      e.preventDefault();
      btn.disabled    = true;
      btn.textContent = 'Adding…';

      fetch('/cart/add.js', {
        method: 'POST',
        credentials: 'same-origin',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          id: parseInt(variantId, 10),
          quantity: 1,
          properties: {
            "_source": "Aftersell",
            "_attribution": "CTA"
          }
        })
      })
      .then(function(r) {
        if (!r.ok) throw new Error('Cart add failed: ' + r.status);
        return r.json();
      })
      .then(function() {
        btn.textContent = 'Added!';
        btn.classList.add('aftersell-cta--added');
        if (typeof window.theme !== 'undefined' && window.theme.cart && window.theme.cart.open) {
          window.theme.cart.open();
        }
        setTimeout(function() {
          btn.textContent = CTA_LABEL;
          btn.classList.remove('aftersell-cta--added');
          btn.disabled = false;
        }, 2500);
      })
      .catch(function(err) {
        console.error('[AfterSell carousel] Add to cart error:', err);
        btn.textContent = 'Try Again';
        btn.disabled    = false;
      });
    });
  }

  function initSplide() {
    function mount() {
      if (typeof window.Splide === 'undefined') {
        setTimeout(mount, 50);
        return;
      }

      splideInstance = new Splide('#aftersell-splide-' + SECTION_ID, {
        type:       'slide',
        perPage:    4,
        perMove:    4,
        gap:        '10px',
        pagination: false,
        arrows:     false,
        speed:      350,
        drag:       false,
        breakpoints: {
          768: { perPage: 2, perMove: 2, drag: 'free', snap: true },
          480: { perPage: 1, perMove: 1, drag: 'free', snap: true, padding: { right: '25%' } }
        }
      }).mount();

      function updateArrows() {
        var idx = splideInstance.index;
        var end = splideInstance.length - splideInstance.options.perPage;
        prevBtn.disabled = idx <= 0;
        nextBtn.disabled = idx >= end;
      }

      prevBtn.addEventListener('click', function() { splideInstance.go('<'); });
      nextBtn.addEventListener('click', function() { splideInstance.go('>'); });
      splideInstance.on('moved', updateArrows);
      updateArrows();
    }
    mount();
  }

  function clearSkeletons() { list.innerHTML = ''; }

  evaluate();
})();
</script>

{% endif %}

{% schema %}
{
  "name": "Aftersell Carousel",
  "settings": [
    { "type": "text",  "id": "strategy_id",  "label": "AfterSell Strategy ID", "default": "ADD_ID_HERE" },
    { "type": "text",  "id": "heading",      "label": "Heading",               "default": "You might also like" },
    { "type": "text",  "id": "cta_label",    "label": "CTA Button Label",      "default": "Add to cart" },
    { "type": "range", "id": "max_products", "label": "Max Products to Show",  "default": 8, "min": 1, "max": 20, "step": 1 }
  ],
  "presets": [{ "name": "Aftersell Carousel" }]
}
{% endschema %}

커스터마이징하기

섹션 스키마는 판매자가 편집할 수 있는 네 가지 설정을 제공해요: Strategy ID, Heading, CTA Button Label, Max Products to Show. 테마 편집기에 더 많은 옵션을 노출하려면 {% schema %} 블록에서 설정을 추가하거나 제거하세요. CSS는 .aftersell-* 클래스 이름 아래로 범위가 지정되어 있으며, 768px에서 2개, 480px에서 1개로 줄어드는 Splide 기반 4개 표시 캐러셀을 포함해요. 테마에 맞게 자유롭게 편집하세요 - API 호출이 작동하는 데 필수적인 부분은 없어요.

카트 컨텍스트: 커스텀 카트 업셀 블록

이 패턴은 구조적으로 PDP 패턴과 동일하지만 한 가지 중요한 차이가 있어요: 상품 컨텍스트 배열이 현재 보고 있는 상품 대신 카트의 라인 아이템으로 구성돼요. 그러면 Strategy는 쇼핑객이 추가한 모든 상품을 받아서 카트 전체를 기반으로 추천을 반환해요. 구현 위치는 커스텀 카트 코드가 있는 곳이에요 - 카트 드로어를 렌더링하는 Liquid 섹션, 헤드리스 스토어프런트의 커스텀 블록, 또는 cart.liquid 같은 테마 템플릿. API 호출의 형태와 응답 처리는 PDP 예제와 동일하며, products 배열만 달라요. 구조는 다음과 같아요:

var products = {{ cart.items | json }}.map(function(item) {
  return {
    productId: 'gid://shopify/Product/' + item.product_id,
    variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
    quantity:  item.quantity,
    price:     item.price / 100
    // ...other fields as needed
  };
});

페이로드의 나머지(cart, customer, session, cartToken)와 /api/public/strategy/evaluate에 대한 fetch 호출은 위 PDP 패턴과 동일해요 - products 배열만 [productContext]에서 카트 기반 배열로 바뀌어요.

Strategy가 반환할 때 일어나는 일

어떤 컨텍스트를 보냈든 응답 형태는 동일해요:

{
  "success": true,
  "products": [ /* enriched recommended products */ ],
  "evaluationId": "f3a1c2e0-...",
  "resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
  "meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}

evaluationId는 이 평가의 고유 ID예요. 이를 캡처하여 렌더링하는 상품에 첨부하면, 이후 발생하는 주문을 해당 추천을 생성한 정확한 평가로 어트리뷰션할 수 있어요 - 아래 어트리뷰션을 참고하세요. products 배열을 렌더링하는 방법은 전적으로 테마 코드에 달려 있어요. 위 PDP 스니펫은 변형 선택기와 장바구니 담기 버튼이 있는 카드 캐러셀로 렌더링하고, 커스텀 카트 블록은 드로어 안에 세로 목록으로 렌더링할 수 있어요. 전체 요청 및 응답 스키마는 Strategy 평가 API 레퍼런스를 참고하세요.

상품이 반환되지 않을 때

Strategy가 상품을 반환하지 않으면(products: []) 처리 방법은 여러분의 코드에 달려 있어요. 위 PDP 스니펫은 캐러셀을 완전히 숨겨요. 커스텀 카트 블록은 카트의 기본 업셀 목록으로 폴백하거나, 아무것도 렌더링하지 않을 수도 있어요. 빈 응답을 피하려면 Strategy에 Catch all을 구성하여 항상 반환할 폴백 상품이 있도록 하세요. Catch all 설정 방법은 Strategy 만들기 페이지를 참고하세요.

커스텀 통합을 위한 팁

컨텍스트는 Liquid로 구성하세요. Liquid는 렌더링 시점에 실행되며 상품, 카트, 고객, 상점, 요청 등 전체 Shopify 객체 그래프에 접근할 수 있어요. 클라이언트 측 호출에 의존하기보다 서버 측에서 페이로드를 채우는 데 사용하세요.
API 키를 공개 저장소에 노출하지 마세요. API 키는 브라우저로 전달되는 테마 코드에 포함되는데, 그건 괜찮아요. 하지만 동일한 테마를 공개 저장소에 붙여넣거나 번들을 외부에 공유하지 마세요.
Catch all을 사용하세요. 슬롯이 사라지면 스토어프런트 경험이 망가져 보여요. 안전한 기본 상품 몇 개로 구성된 Catch all이 UI를 일관되게 유지해요.
필요한 곳에 캐싱하세요. Strategies API는 서버 측에서 가벼운 캐싱을 수행하지만(meta.servedFromCache), 트래픽이 많은 PDP에서는 클라이언트에서도 호출을 디바운스하거나 메모이즈하는 것이 좋아요 (예: 같은 세션에서 같은 상품이 두 번 렌더링될 때 다시 호출하지 않기).

어트리뷰션

쇼핑객이 스니펫의 장바구니 담기 버튼을 클릭하면 /cart/add.js 호출이 카트 아이템에 라인 아이템 속성을 첨부해요:

properties: {
  "_source": "Aftersell",
  "_attribution": "CTA"
}

이 속성은 라인 아이템과 함께 Shopify 주문까지 전달되어 라인 아이템 레코드에 표시돼요. 이후 수익 어트리뷰션, 주문 필터링, 또는 라인 아이템 속성을 읽는 분석 도구에 활용할 수 있어요. 키와 값은 관례일 뿐 필수 사항이 아니에요 - 여기에 무엇을 넣든 API 호출은 동일하게 작동해요. 자신의 어트리뷰션 모델에 맞게 변경하세요. 예를 들어:

properties: {
  "_source": "PDP Carousel",
  "_strategy_id": "{{ section.settings.strategy_id }}",
  "_campaign": "summer-2026"
}

밑줄(_)로 시작하는 속성 키는 카트와 체크아웃 UI에서 숨겨지지만 주문에는 여전히 첨부돼요. 쇼핑객에게 보이지 않아야 하는 어트리뷰션 전용 메타데이터에는 밑줄 접두사를 사용하세요.

카트 컨텍스트 구현에도 같은 패턴을 적용하세요 - 커스텀 업셀 블록에서 실행하는 모든 장바구니 담기 호출에 필요한 속성을 자유롭게 담을 수 있어요.

평가로 어트리뷰션 연결하기

주문을 단순히 “Strategy에서 왔다”가 아니라 상품을 추천한 정확한 평가로 연결하려면, 응답에서 evaluationId를 캡처하여 __as_offer_id 속성으로 라인 아이템에 첨부하세요. AfterSell이 이 키를 읽으므로, 이 키가 태그된 주문은 보고서에서 특정 평가로 어트리뷰션돼요. evaluate() 핸들러에서 응답의 ID를 보관하세요:

.then(function(data) {
  if (!data || !data.success || !data.products || !data.products.length) {
    clearSkeletons(); return;
  }
  evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
  renderCards(data.products.slice(0, MAX_PRODUCTS));
})

그런 다음 장바구니 담기 속성에 포함하세요:

properties: Object.assign(
  { "_source": "Aftersell", "_attribution": "CTA" },
  evaluationId ? { "__as_offer_id": evaluationId } : {}
)

__as_offer_id의 이중 밑줄을 유지하세요 - AfterSell이 찾는 키이며, 밑줄 접두사가 쇼핑객에게 보이지 않도록 해줘요. evaluationId가 없는 경우(예: 반환된 상품이 없는 경우)에는 빈 값을 보내지 말고 속성을 생략하세요.

전략

구매 후 업셀

구독 업그레이드

체크아웃 업셀

감사 페이지

분석

개요

필요한 것

PDP 컨텍스트: 섹션 스니펫

설치하기

섹션이 전송하는 것

스니펫

커스터마이징하기

카트 컨텍스트: 커스텀 카트 업셀 블록

Strategy가 반환할 때 일어나는 일

상품이 반환되지 않을 때

커스텀 통합을 위한 팁

어트리뷰션

평가로 어트리뷰션 연결하기

​개요

​필요한 것

​PDP 컨텍스트: 섹션 스니펫

​설치하기

​섹션이 전송하는 것

​스니펫

​커스터마이징하기

​카트 컨텍스트: 커스텀 카트 업셀 블록

​Strategy가 반환할 때 일어나는 일

​상품이 반환되지 않을 때

​커스텀 통합을 위한 팁

​어트리뷰션

​평가로 어트리뷰션 연결하기

개요

필요한 것

PDP 컨텍스트: 섹션 스니펫

설치하기

섹션이 전송하는 것

스니펫

커스터마이징하기

카트 컨텍스트: 커스텀 카트 업셀 블록

Strategy가 반환할 때 일어나는 일

상품이 반환되지 않을 때

커스텀 통합을 위한 팁

어트리뷰션

평가로 어트리뷰션 연결하기