Integracja niestandardowa

Przegląd

Gdy ani natywne powierzchnie Aftersell (post-purchase, checkout, Upcart), ani gotowa integracja nie pasują, możesz samodzielnie wywoływać Strategies API ze swojego szablonu Shopify i renderować zwrócone produkty w dowolny sposób. Wzorzec jest zawsze taki sam: zbuduj ładunek kontekstu z Liquid (dzięki temu atrybuty Shopify, takie jak bieżący produkt, zawartość koszyka i pola klienta, są uzupełniane w momencie renderowania), wyślij go metodą POST do /api/public/strategy/evaluate i wyrenderuj odpowiedź. Ta strona opisuje dwa wzorce implementacji:

Kontekst PDP — umieść sekcję na stronach produktów, która wywołuje API z aktualnie przeglądanym produktem i renderuje karuzelę zwróconych rekomendacji.
Kontekst koszyka — wyrenderuj blok upsell wewnątrz niestandardowego koszyka, który wywołuje API ze wszystkimi bieżącymi pozycjami koszyka i renderuje zwrócone produkty.

Tym, co różni oba wzorce, jest kształt kontekstu produktu: pojedynczy produkt na PDP, tablica wszystkich pozycji w koszyku.

Czego potrzebujesz

Twój klucz API Strategii. W Aftersell przejdź do Settings → Product Strategy i na karcie Security Token skopiuj swój token (to jest Twój klucz API Strategii).
ID Strategii. Otwórz Strategię, którą chcesz uruchomić, w edytorze Strategii Aftersell i skopiuj jej ID.
Dostęp do kodu szablonu. Będziesz dodawać sekcję Liquid (PDP) lub blok (niestandardowy koszyk) do swojego szablonu Shopify — Online Store → Themes → … → Edit code.

Twój klucz API Strategii znajduje się w kodzie szablonu po stronie klienta, co sprawia, że jest widoczny dla każdego, kto przegląda źródło strony. Traktuj go jak publiczne dane uwierzytelniające witryny sklepu i zrotuj go w Aftersell w Settings → Product Strategy, jeśli kiedykolwiek zostanie ujawniony w sposób, którego nie planowałeś.

Kontekst PDP: snippet sekcji

Ten wzorzec dodaje sekcję Shopify do Twojej strony produktu. Podczas renderowania strony Liquid osadza w ładunku atrybuty bieżącego produktu, koszyka i klienta, a następnie JavaScript wysyła żądanie do Strategies API i renderuje zwrócone produkty w karuzeli Splide.

Instalacja

W panelu administracyjnym Shopify przejdź do Online Store → Themes, kliknij … przy swoim szablonie i wybierz Edit code.
W folderze Sections utwórz nowy plik o nazwie aftersell-upsell-carousel.liquid.
Wklej poniższy snippet do nowego pliku i zastąp YOUR_STRATEGY_API_KEY kluczem API z Aftersell.
Zapisz.
Otwórz szablon produktu (zazwyczaj templates/product.json lub sections/main-product.liquid) i dodaj sekcję Aftersell Carousel w miejscu, w którym ma się pojawić karuzela. Z poziomu edytora szablonu możesz też przeciągnąć ją bezpośrednio na stronę produktu.
W ustawieniach sekcji wklej swoje ID Strategii.

Co wysyła sekcja

Dla każdego wyświetlenia PDP ładunek zawiera:

products — jednoelementową tablicę zawierającą aktualnie przeglądany produkt (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
cart — sumę częściową, liczbę sztuk, liczbę pozycji bieżącego koszyka kupującego (pomijane, jeśli koszyk jest pusty).
cartToken — dzięki temu API może powiązać tę ocenę z tą samą sesją.
customer — tagi, kraj, prowincję, ustawienia regionalne, liczbę zamówień, łączne wydatki i flagę zgody na marketing, ale tylko jeśli kupujący jest zalogowany.
session — kod waluty z shop.currency.

Sekcja domyślnie nie wysyła parametrów UTM. Jeśli chcesz targetowania opartego na UTM na PDP, przechwyć je po stronie klienta i dodaj do obiektu session przed wywołaniem fetch.

Snippet

{% 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 %}

Karuzela produktów zasilana Strategią wyrenderowana na stronie produktu Shopify

Dostosowywanie

Schema sekcji udostępnia cztery ustawienia edytowalne przez sprzedawcę: Strategy ID, Heading, CTA Button Label i Max Products to Show. Dodawaj lub usuwaj ustawienia w bloku {% schema %}, aby udostępnić więcej opcji w edytorze szablonu. CSS jest ograniczony do klas .aftersell-* i zawiera napędzaną Splide karuzelę 4-elementową, która przechodzi na 2 elementy przy 768px i 1 element przy 480px. Możesz go dowolnie edytować, aby dopasować do swojego szablonu — nic z tego nie jest wymagane do działania wywołania API.

Kontekst koszyka: niestandardowy blok upsell w koszyku

Ten wzorzec jest strukturalnie taki sam jak wzorzec PDP, z jedną kluczową różnicą: tablica kontekstu produktów jest budowana z pozycji koszyka zamiast z aktualnie przeglądanego produktu. Strategia otrzymuje wtedy każdy produkt dodany przez kupującego i zwraca rekomendacje na podstawie koszyka jako całości. Implementacja znajduje się tam, gdzie znajduje się kod Twojego niestandardowego koszyka — sekcja Liquid renderująca cart drawer, niestandardowy blok w headlessowej witrynie sklepu lub szablon taki jak cart.liquid. Kształt wywołania API i obsługa odpowiedzi są identyczne jak w przykładzie PDP — różni się tylko tablica products. Struktura wygląda tak:

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

Reszta ładunku (cart, customer, session, cartToken) oraz wywołanie fetch do /api/public/strategy/evaluate pozostają niezmienione względem powyższego wzorca PDP — jedynie tablica products zamienia się z [productContext] na tablicę pochodzącą z koszyka.

Co się dzieje, gdy Strategia zwraca wynik

Kształt odpowiedzi jest taki sam niezależnie od tego, który kontekst został wysłany:

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

evaluationId to unikalny identyfikator tej oceny. Jeśli go przechwycisz i dołączysz do renderowanych produktów, możesz przypisać wynikowe zamówienie do dokładnie tej rekomendacji, która je wygenerowała — zobacz sekcję Atrybucja poniżej. Sposób renderowania tablicy products zależy całkowicie od kodu Twojego szablonu. Powyższy snippet PDP renderuje je jako karuzelę kart z selektorami wariantów i przyciskami dodawania do koszyka; niestandardowy blok koszyka mógłby renderować je jako pionową listę wewnątrz drawera. Pełny schemat żądania i odpowiedzi znajdziesz w referencji API Evaluate Strategy.

Gdy żaden produkt nie zostanie zwrócony

Jeśli Strategia nie zwraca produktów (products: []), sposób obsługi zależy od Twojego kodu. Powyższy snippet PDP całkowicie ukrywa karuzelę. Niestandardowy blok koszyka mógłby wrócić do domyślnej listy upselli koszyka albo po prostu nie renderować nic. Aby uniknąć pustej odpowiedzi, skonfiguruj w Strategii regułę Catch all, dzięki której zawsze będzie istniał zapasowy produkt do zwrócenia. Zobacz stronę Budowanie Strategii, aby dowiedzieć się, jak skonfigurować Catch all.

Wskazówki dotyczące integracji niestandardowych

Buduj kontekst w Liquid. Liquid działa w momencie renderowania i ma dostęp do pełnego grafu obiektów Shopify — product, cart, customer, shop, request. Używaj go do wypełniania ładunku po stronie serwera, zamiast sięgać po wywołania po stronie klienta.
Trzymaj klucz API z dala od publicznych repozytoriów. Trafi on do kodu Twojego szablonu, który jest dostarczany do przeglądarki — to w porządku. Nie wklejaj jednak tego samego szablonu do publicznego repozytorium ani nie udostępniaj paczki na zewnątrz.
Używaj Catch all. Doświadczenia w witrynie sklepu wyglądają na zepsute, gdy slot znika. Catch all z niewielkim zestawem bezpiecznych produktów domyślnych utrzymuje spójność interfejsu.
Cache’uj tam, gdzie ma to sens. Strategies API stosuje lekkie cache’owanie po stronie serwera (meta.servedFromCache), ale na PDP o dużym ruchu warto też debounce’ować lub memoizować wywołania po stronie klienta (np. nie wywoływać ponownie, gdy ten sam produkt jest renderowany dwa razy w jednej sesji).

Atrybucja

Gdy kupujący kliknie przycisk dodawania do koszyka w snippecie, wywołanie /cart/add.js dołącza do pozycji koszyka właściwości pozycji (line item properties):

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

Te właściwości podróżują z pozycją aż do zamówienia Shopify, gdzie pojawiają się w rekordzie pozycji. Możesz ich używać dalej do atrybucji przychodu, filtrowania zamówień lub zasilania narzędzi analitycznych, które odczytują właściwości pozycji. Klucze i wartości to konwencje, a nie wymagania — wywołanie API działa tak samo niezależnie od tego, co tu umieścisz. Zmień je, aby pasowały do Twojego własnego modelu atrybucji. Na przykład:

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

Klucze właściwości zaczynające się od podkreślnika (_) są ukryte w interfejsie koszyka i checkoutu, ale nadal są dołączane do zamówienia. Używaj prefiksu podkreślnika dla metadanych przeznaczonych wyłącznie do atrybucji, których kupujący nie mają widzieć.

Zastosuj ten sam wzorzec w implementacji z kontekstem koszyka — każde wywołanie dodania do koszyka z niestandardowego bloku upsell może przenosić dowolne właściwości, jakich potrzebujesz.

Atrybucja do konkretnej oceny

Aby powiązać zamówienie z dokładną oceną, która zarekomendowała produkt — a nie tylko z faktem, że „pochodzi ze Strategii” — przechwyć evaluationId z odpowiedzi i dołącz go do pozycji pod właściwością __as_offer_id. AfterSell odczytuje ten klucz, więc zamówienia nim oznaczone są przypisywane do konkretnej oceny w raportowaniu. W handlerze evaluate() zachowaj identyfikator z odpowiedzi:

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

Następnie uwzględnij go we właściwościach dodawania do koszyka:

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

Zachowaj podwójny podkreślnik w __as_offer_id — to klucz, którego szuka AfterSell, a prefiks podkreślnika ukrywa go przed kupującymi. Jeśli evaluationId nie istnieje (na przykład nie zwrócono żadnych produktów), pomiń tę właściwość, zamiast wysyłać pustą wartość.

Strategie

Upselle po zakupie

Ulepszenia subskrypcji

Upselle przy realizacji zakupu

Strona z podziękowaniem

Analityka

Przegląd

Czego potrzebujesz

Kontekst PDP: snippet sekcji

Instalacja

Co wysyła sekcja

Snippet

Dostosowywanie

Kontekst koszyka: niestandardowy blok upsell w koszyku

Co się dzieje, gdy Strategia zwraca wynik

Gdy żaden produkt nie zostanie zwrócony

Wskazówki dotyczące integracji niestandardowych

Atrybucja

Atrybucja do konkretnej oceny

​Przegląd

​Czego potrzebujesz

​Kontekst PDP: snippet sekcji

​Instalacja

​Co wysyła sekcja

​Snippet

​Dostosowywanie

​Kontekst koszyka: niestandardowy blok upsell w koszyku

​Co się dzieje, gdy Strategia zwraca wynik

​Gdy żaden produkt nie zostanie zwrócony

​Wskazówki dotyczące integracji niestandardowych

​Atrybucja

​Atrybucja do konkretnej oceny

Przegląd

Czego potrzebujesz

Kontekst PDP: snippet sekcji

Instalacja

Co wysyła sekcja

Snippet

Dostosowywanie

Kontekst koszyka: niestandardowy blok upsell w koszyku

Co się dzieje, gdy Strategia zwraca wynik

Gdy żaden produkt nie zostanie zwrócony

Wskazówki dotyczące integracji niestandardowych

Atrybucja

Atrybucja do konkretnej oceny