Integrazione personalizzata

Panoramica

Quando né le superfici native di Aftersell (post-acquisto, checkout, Upcart) né un’integrazione preconfezionata fanno al caso tuo, puoi chiamare tu stesso la Strategies API dal tuo tema Shopify e visualizzare i prodotti restituiti come preferisci. Lo schema è lo stesso in ogni caso: costruisci un payload di contesto da Liquid (in modo che gli attributi Shopify come il prodotto corrente, il contenuto del carrello e i campi del cliente vengano compilati al momento del rendering), fai una POST a /api/public/strategy/evaluate e visualizzi la risposta. Questa pagina copre due modelli di implementazione:

Contesto PDP - inserisci una sezione nelle pagine prodotto che chiama l’API con il prodotto attualmente visualizzato e mostra un carosello di raccomandazioni restituite.
Contesto carrello - visualizza un blocco di upsell all’interno di un carrello personalizzato che chiama l’API con tutte le voci attualmente nel carrello e mostra i prodotti restituiti.

Ciò che cambia tra i due è la forma del contesto prodotto: un singolo prodotto sulla PDP, un array di tutte le voci nel carrello.

Di cosa avrai bisogno

La tua Strategy API key. In Aftersell, vai su Settings → Product Strategy e, nella scheda Security Token, copia il tuo token (questa è la tua Strategy API key).
Lo Strategy ID. Apri la Strategy che vuoi eseguire nell’editor delle Strategy di Aftersell e copia il suo ID.
Accesso al codice del tema. Dovrai aggiungere una sezione Liquid (PDP) o un blocco (carrello personalizzato) al tuo tema Shopify - Online Store → Themes → … → Edit code.

La tua Strategy API key risiede nel codice del tema lato client, il che la rende visibile a chiunque visualizzi il codice sorgente della pagina. Trattala come una credenziale pubblica della vetrina e ruotala da Aftersell Settings → Product Strategy se dovesse mai essere esposta in un modo non voluto.

Contesto PDP: snippet della sezione

Questo modello aggiunge una sezione Shopify alla tua pagina prodotto. Quando la pagina viene renderizzata, Liquid incorpora nel payload gli attributi del prodotto corrente, del carrello e del cliente, poi JavaScript effettua una POST alla Strategies API e mostra i prodotti restituiti in un carosello Splide.

Installazione

Nel tuo pannello di amministrazione Shopify, vai su Online Store → Themes, clicca su … sul tuo tema e seleziona Edit code.
Nella cartella Sections, crea un nuovo file chiamato aftersell-upsell-carousel.liquid.
Incolla lo snippet qui sotto nel nuovo file e sostituisci YOUR_STRATEGY_API_KEY con l’API key di Aftersell.
Salva.
Apri il tuo template prodotto (di solito templates/product.json o sections/main-product.liquid) e aggiungi la sezione Aftersell Carousel nel punto in cui vuoi che appaia il carosello. Dall’editor del tema puoi anche trascinarla direttamente sulla pagina prodotto.
Nelle impostazioni della sezione, incolla il tuo Strategy ID.

Cosa invia la sezione

Per ogni visualizzazione della PDP, il payload include:

products - un array con un solo elemento contenente il prodotto attualmente visualizzato (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
cart - subtotale, numero di articoli e numero di righe del carrello corrente dell’acquirente (omesso se il carrello è vuoto).
cartToken - in modo che l’API possa collegare questa valutazione alla stessa sessione.
customer - tag, paese, provincia, lingua, numero di ordini, spesa totale e flag accepts-marketing, ma solo se l’acquirente ha effettuato l’accesso.
session - codice valuta da shop.currency.

La sezione non invia i parametri UTM per impostazione predefinita. Se vuoi un targeting basato su UTM sulla PDP, acquisiscili lato client e aggiungili all’oggetto session prima della fetch.

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

Un carosello di prodotti alimentato da una Strategy visualizzato su una pagina prodotto Shopify

Personalizzazione

Lo schema della sezione espone quattro impostazioni modificabili dal merchant: Strategy ID, Heading, CTA Button Label e Max Products to Show. Aggiungi o rimuovi impostazioni nel blocco {% schema %} per esporre più controlli nell’editor del tema. Il CSS è delimitato sotto nomi di classe .aftersell-* e include un carosello Splide a 4 elementi che passa a 2 elementi a 768px e a 1 elemento a 480px. Modificalo liberamente per adattarlo al tuo tema: nulla di tutto ciò è necessario per il funzionamento della chiamata API.

Contesto carrello: blocco di upsell in un carrello personalizzato

Questo modello è strutturalmente identico a quello della PDP, con una differenza chiave: l’array del contesto prodotto viene costruito dalle voci del carrello invece che dal prodotto attualmente visualizzato. La Strategy riceve quindi ogni articolo che l’acquirente ha aggiunto e restituisce raccomandazioni basate sul carrello nel suo insieme. L’implementazione vive ovunque risieda il codice del tuo carrello personalizzato: una sezione Liquid che renderizza il cart drawer, un blocco personalizzato in una vetrina headless o un template del tema come cart.liquid. La forma della chiamata API e la gestione della risposta sono identiche all’esempio della PDP: cambia solo l’array products. La struttura è questa:

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

Il resto del payload (cart, customer, session, cartToken) e la chiamata fetch a /api/public/strategy/evaluate rimangono invariati rispetto al modello PDP qui sopra: solo l’array products passa da [productContext] all’array derivato dal carrello.

Cosa succede quando la Strategy restituisce un risultato

La forma della risposta è la stessa indipendentemente dal contesto che hai inviato:

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

L’evaluationId è un id univoco per questa valutazione. Se lo acquisisci e lo alleghi ai prodotti che visualizzi, puoi attribuire l’ordine risultante esattamente alla raccomandazione che lo ha generato - vedi Attribuzione qui sotto. Il modo in cui visualizzi l’array products dipende interamente dal codice del tuo tema. Lo snippet PDP qui sopra li mostra come un carosello di schede con selettori di varianti e pulsanti di aggiunta al carrello; un blocco di carrello personalizzato potrebbe visualizzarli come un elenco verticale all’interno del drawer. Per lo schema completo di richiesta e risposta, consulta il riferimento API Evaluate Strategy.

Quando nessun prodotto viene restituito

Se la Strategy non restituisce alcun prodotto (products: []), spetta al tuo codice decidere come gestirlo. Lo snippet PDP qui sopra nasconde completamente il carosello. Un blocco di carrello personalizzato potrebbe ripiegare sull’elenco di upsell predefinito del carrello, oppure semplicemente non mostrare nulla. Per evitare una risposta vuota, configura un Catch all nella Strategy in modo che ci sia sempre un prodotto di riserva da restituire. Consulta la pagina Costruire le Strategy per scoprire come impostare un Catch all.

Suggerimenti per le integrazioni personalizzate

Costruisci il contesto in Liquid. Liquid viene eseguito al momento del rendering e ha accesso all’intero grafo degli oggetti Shopify: prodotto, carrello, cliente, negozio, richiesta. Usalo per popolare il payload lato server invece di ricorrere a chiamate lato client.
Tieni l’API key fuori dai repository pubblici. Finirà nel codice del tuo tema, che viene consegnato al browser - e questo va bene. Ma non incollare lo stesso tema in un repository pubblico né condividere il bundle esternamente.
Usa un Catch all. Le esperienze in vetrina sembrano rotte quando uno slot scompare. Un Catch all con un piccolo set di prodotti sicuri di default mantiene l’interfaccia coerente.
Metti in cache dove ha senso. La Strategies API fa un leggero caching lato server (meta.servedFromCache), ma per le PDP ad alto traffico potresti anche voler applicare debounce o memoizzazione alle chiamate lato client (es. non richiamare quando lo stesso prodotto viene renderizzato due volte in una sessione).

Attribuzione

Quando un acquirente clicca sul pulsante di aggiunta al carrello nello snippet, la chiamata /cart/add.js allega delle line item properties all’articolo del carrello:

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

Queste proprietà viaggiano con la voce del carrello fino all’ordine Shopify, dove compaiono nel record della voce. Puoi usarle a valle per attribuire i ricavi, filtrare gli ordini o alimentare strumenti di analytics che leggono le line item properties. Le chiavi e i valori sono convenzioni, non requisiti: la chiamata API funziona allo stesso modo indipendentemente da cosa inserisci qui. Modificale per adattarle al tuo modello di attribuzione. Per esempio:

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

Le chiavi di proprietà che iniziano con un trattino basso (_) sono nascoste nell’interfaccia del carrello e del checkout ma restano comunque allegate all’ordine. Usa il prefisso con trattino basso per i metadati di sola attribuzione che non vuoi far vedere agli acquirenti.

Applica lo stesso schema nell’implementazione con contesto carrello: qualsiasi chiamata di aggiunta al carrello effettuata da un blocco di upsell personalizzato può portare con sé tutte le proprietà di cui hai bisogno.

Attribuire alla valutazione

Per collegare un ordine alla valutazione esatta che ha raccomandato il prodotto - anziché solo a “proviene da una Strategy” - acquisisci l’evaluationId dalla risposta e allegalo alla voce del carrello sotto la proprietà __as_offer_id. AfterSell legge questa chiave, quindi gli ordini contrassegnati con essa vengono attribuiti alla valutazione specifica nella reportistica. Nell’handler evaluate(), conserva l’id dalla risposta:

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

Poi includilo nelle proprietà di aggiunta al carrello:

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

Mantieni il doppio trattino basso su __as_offer_id: è la chiave che AfterSell cerca, e il prefisso con trattino basso la tiene nascosta agli acquirenti. Se evaluationId è assente (per esempio, se non è stato restituito alcun prodotto), ometti la proprietà anziché inviare un valore vuoto.

Strategie

Upsell post-acquisto

Upgrade di abbonamento

Upsell al checkout

Pagina di ringraziamento

Analisi

Panoramica

Di cosa avrai bisogno

Contesto PDP: snippet della sezione

Installazione

Cosa invia la sezione

Lo snippet

Personalizzazione

Contesto carrello: blocco di upsell in un carrello personalizzato

Cosa succede quando la Strategy restituisce un risultato

Quando nessun prodotto viene restituito

Suggerimenti per le integrazioni personalizzate

Attribuzione

Attribuire alla valutazione

​Panoramica

​Di cosa avrai bisogno

​Contesto PDP: snippet della sezione

​Installazione

​Cosa invia la sezione

​Lo snippet

​Personalizzazione

​Contesto carrello: blocco di upsell in un carrello personalizzato

​Cosa succede quando la Strategy restituisce un risultato

​Quando nessun prodotto viene restituito

​Suggerimenti per le integrazioni personalizzate

​Attribuzione

​Attribuire alla valutazione

Panoramica

Di cosa avrai bisogno

Contesto PDP: snippet della sezione

Installazione

Cosa invia la sezione

Lo snippet

Personalizzazione

Contesto carrello: blocco di upsell in un carrello personalizzato

Cosa succede quando la Strategy restituisce un risultato

Quando nessun prodotto viene restituito

Suggerimenti per le integrazioni personalizzate

Attribuzione

Attribuire alla valutazione