Integración personalizada

Descripción general

Cuando ni las superficies nativas de Aftersell (post-compra, checkout, Upcart) ni una integración empaquetada se ajustan a tus necesidades, puedes llamar tú mismo a la API de Strategies desde tu tema de Shopify y mostrar los productos devueltos como prefieras. El patrón es el mismo en todos los casos: construye una carga útil de contexto desde Liquid (para que los atributos de Shopify como el producto actual, el contenido del carrito y los campos del cliente se rellenen en el momento de renderizar), haz POST a /api/public/strategy/evaluate y muestra la respuesta. Esta página cubre dos patrones de implementación:

Contexto PDP: coloca una sección en las páginas de producto que llama a la API con el producto que se está viendo actualmente y muestra un carrusel con las recomendaciones devueltas.
Contexto de carrito: muestra un bloque de upsell dentro de un carrito personalizado que llama a la API con todas las líneas de pedido actuales del carrito y muestra los productos devueltos.

Lo que difiere entre ambos es la forma del contexto de producto: un solo producto en la PDP, un array con todas las líneas de pedido en el carrito.

Qué necesitarás

Tu clave de API de Strategy. En Aftersell, ve a Settings → Product Strategy y, en la tarjeta Security Token, copia tu token (esta es tu clave de API de Strategy).
El ID de la Strategy. Abre la Strategy que quieres ejecutar en el editor de Strategies de Aftersell y copia su ID.
Acceso al código del tema. Añadirás una sección Liquid (PDP) o un bloque (carrito personalizado) a tu tema de Shopify: Online Store → Themes → … → Edit code.

Tu clave de API de Strategy reside en el código del tema del lado del cliente, lo que la hace visible para cualquiera que vea el código fuente de la página. Trátala como una credencial pública de la tienda y rótala desde Settings → Product Strategy en Aftersell si alguna vez queda expuesta de una forma que no pretendías.

Contexto PDP: fragmento de sección

Este patrón añade una sección de Shopify a tu página de producto. Cuando la página se renderiza, Liquid incorpora los atributos del producto actual, el carrito y el cliente en la carga útil; luego JavaScript hace un post a la API de Strategies y muestra los productos devueltos en un carrusel de Splide.

Instalación

En tu panel de administración de Shopify, ve a Online Store → Themes, haz clic en … en tu tema y selecciona Edit code.
En la carpeta Sections, crea un nuevo archivo llamado aftersell-upsell-carousel.liquid.
Pega el fragmento a continuación en el nuevo archivo y reemplaza YOUR_STRATEGY_API_KEY con la clave de API de Aftersell.
Guarda.
Abre tu plantilla de producto (normalmente templates/product.json o sections/main-product.liquid) y añade la sección Aftersell Carousel donde quieras que aparezca el carrusel. Desde el editor de temas, también puedes arrastrarla directamente a la página de producto.
En la configuración de la sección, pega tu Strategy ID.

Qué envía la sección

Para cada vista de la PDP, la carga útil incluye:

products: un array de un solo elemento que contiene el producto que se está viendo actualmente (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
cart: subtotal, número de artículos y número de líneas del carrito actual del comprador (se omite si el carrito está vacío).
cartToken: para que la API pueda vincular esta evaluación a la misma sesión.
customer: etiquetas, país, provincia, configuración regional, número de pedidos, gasto total y el indicador de aceptación de marketing, pero solo si el comprador ha iniciado sesión.
session: código de moneda de shop.currency.

La sección no envía parámetros UTM de forma predeterminada. Si quieres segmentación basada en UTM en la PDP, captúralos del lado del cliente y añádelos al objeto session antes del fetch.

El fragmento

{% 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 carrusel de productos impulsado por una Strategy renderizado en una página de producto de Shopify

Personalización

El schema de la sección expone cuatro ajustes editables por el comerciante: Strategy ID, Heading, CTA Button Label y Max Products to Show. Añade o elimina ajustes en el bloque {% schema %} para exponer más opciones en el editor de temas. El CSS está delimitado bajo nombres de clase .aftersell-* e incluye un carrusel de 4 elementos impulsado por Splide que pasa a 2 elementos a 768px y a 1 elemento a 480px. Edítalo libremente para que coincida con tu tema: nada de esto es necesario para que la llamada a la API funcione.

Contexto de carrito: bloque de upsell de carrito personalizado

Este patrón es estructuralmente igual al de la PDP, con una diferencia clave: el array de contexto de producto se construye a partir de las líneas de pedido del carrito en lugar del producto que se está viendo actualmente. La Strategy recibe entonces cada artículo que el comprador ha añadido y devuelve recomendaciones basadas en el carrito en su conjunto. La implementación vive donde viva el código de tu carrito personalizado: una sección Liquid que renderiza el cajón del carrito, un bloque personalizado en una tienda headless o una plantilla de tema como cart.liquid. La forma de la llamada a la API y el manejo de la respuesta son idénticos al ejemplo de la PDP; solo difiere el array products. La estructura se ve así:

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

El resto de la carga útil (cart, customer, session, cartToken) y la llamada fetch a /api/public/strategy/evaluate no cambian respecto al patrón de la PDP anterior; solo el array products cambia de [productContext] al array derivado del carrito.

Qué pasa cuando la Strategy devuelve un resultado

La forma de la respuesta es la misma independientemente del contexto que hayas enviado:

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

El evaluationId es un id único de esta evaluación. Si lo capturas y lo adjuntas a los productos que muestras, puedes atribuir el pedido resultante a la recomendación exacta que lo produjo: consulta Atribución más abajo. La forma en que muestras el array products depende por completo del código de tu tema. El fragmento de la PDP anterior los muestra como un carrusel de tarjetas con selectores de variantes y botones de añadir al carrito; un bloque de carrito personalizado podría mostrarlos como una lista vertical dentro del cajón. Para el esquema completo de solicitud y respuesta, consulta la referencia de la API Evaluate Strategy.

Cuando no se devuelve ningún producto

Si la Strategy no devuelve productos (products: []), depende de tu código cómo manejarlo. El fragmento de la PDP anterior oculta el carrusel por completo. Un bloque de carrito personalizado podría recurrir a la lista de upsell predeterminada del carrito, o simplemente no mostrar nada. Para evitar una respuesta vacía, configura un Catch all en la Strategy de modo que siempre haya un producto de respaldo para devolver. Consulta la página Crear Strategies para saber cómo configurar un Catch all.

Consejos para integraciones personalizadas

Construye el contexto en Liquid. Liquid se ejecuta en el momento de renderizar y tiene acceso al grafo completo de objetos de Shopify: producto, carrito, cliente, tienda, solicitud. Úsalo para rellenar la carga útil del lado del servidor en lugar de recurrir a llamadas del lado del cliente.
Mantén la clave de API fuera de repositorios públicos. Terminará en el código de tu tema, que se envía al navegador; eso está bien. Pero no pegues el mismo tema en un repositorio público ni compartas el paquete externamente.
Usa un Catch all. Las experiencias de la tienda se ven rotas cuando un espacio desaparece. Un Catch all con un pequeño conjunto de valores predeterminados seguros mantiene la interfaz consistente.
Usa caché donde tenga sentido. La API de Strategies hace un caché ligero del lado del servidor (meta.servedFromCache), pero para PDP de alto tráfico quizás también quieras aplicar debounce o memoizar las llamadas en el cliente (p. ej., no volver a llamar cuando el mismo producto se renderiza dos veces en una sesión).

Atribución

Cuando un comprador hace clic en el botón de añadir al carrito del fragmento, la llamada a /cart/add.js adjunta propiedades de línea de pedido al artículo del carrito:

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

Estas propiedades viajan con la línea de pedido hasta el pedido de Shopify, donde aparecen en el registro de la línea de pedido. Puedes usarlas posteriormente para atribuir ingresos, filtrar pedidos o alimentar herramientas de analítica que leen propiedades de líneas de pedido. Las claves y valores son convenciones, no requisitos: la llamada a la API funciona igual sin importar lo que pongas aquí. Cámbialos para adaptarlos a tu propio modelo de atribución. Por ejemplo:

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

Las claves de propiedad que empiezan con un guion bajo (_) quedan ocultas en la interfaz del carrito y del checkout, pero aun así se adjuntan al pedido. Usa el prefijo de guion bajo para metadatos solo de atribución que no quieres que vean los compradores.

Aplica el mismo patrón en la implementación de contexto de carrito: cualquier llamada de añadir al carrito que hagas desde un bloque de upsell personalizado puede llevar las propiedades que necesites.

Atribuir a la evaluación

Para vincular un pedido con la evaluación exacta que recomendó el producto —en lugar de solo “vino de una Strategy”—, captura el evaluationId de la respuesta y adjúntalo a la línea de pedido bajo la propiedad __as_offer_id. AfterSell lee esta clave, de modo que los pedidos etiquetados con ella se atribuyen a la evaluación específica en los informes. En el controlador evaluate(), conserva el id de la respuesta:

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

Luego inclúyelo en las propiedades de añadir al carrito:

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

Mantén el doble guion bajo en __as_offer_id: es la clave que AfterSell busca, y el prefijo de guion bajo la mantiene oculta para los compradores. Si evaluationId no está presente (por ejemplo, no se devolvieron productos), omite la propiedad en lugar de enviar un valor vacío.

Estrategias

Ventas adicionales poscompra

Mejoras de suscripción

Ventas adicionales en el pago

Página de agradecimiento

Analíticas

Descripción general

Qué necesitarás

Contexto PDP: fragmento de sección

Instalación

Qué envía la sección

El fragmento

Personalización

Contexto de carrito: bloque de upsell de carrito personalizado

Qué pasa cuando la Strategy devuelve un resultado

Cuando no se devuelve ningún producto

Consejos para integraciones personalizadas

Atribución

Atribuir a la evaluación

​Descripción general

​Qué necesitarás

​Contexto PDP: fragmento de sección

​Instalación

​Qué envía la sección

​El fragmento

​Personalización

​Contexto de carrito: bloque de upsell de carrito personalizado

​Qué pasa cuando la Strategy devuelve un resultado

​Cuando no se devuelve ningún producto

​Consejos para integraciones personalizadas

​Atribución

​Atribuir a la evaluación

Descripción general

Qué necesitarás

Contexto PDP: fragmento de sección

Instalación

Qué envía la sección

El fragmento

Personalización

Contexto de carrito: bloque de upsell de carrito personalizado

Qué pasa cuando la Strategy devuelve un resultado

Cuando no se devuelve ningún producto

Consejos para integraciones personalizadas

Atribución

Atribuir a la evaluación