Upsells do Upcart

Visão geral

O Upcart é um app separado do Aftersell, então as Strategies não estão integradas ao módulo Upsells da mesma forma que estão nos fluxos de pós-compra e checkout do Aftersell. Em vez disso, você conecta os dois apps com um pequeno script que chama a API de Strategies diretamente e envia o resultado para o módulo Upsells existente do Upcart por meio da API pública do Upcart. O script é pronto para uso - cole-o uma vez no HTML personalizado do Upcart, substitua dois valores (sua chave de API da Strategy e o ID da Strategy), e o módulo Upsells começará a exibir os produtos que a Strategy retornar.

O que você vai precisar

Sua chave de API da Strategy. No Aftersell, vá em Settings → Product Strategy e, no card Security Token, copie seu token (essa é a sua chave de API da Strategy).
O ID da Strategy. Abra a Strategy que você quer executar no editor de Strategy do Aftersell e copie o ID dela.
O módulo Upsells ativado no Upcart. O script substitui a lista de produtos exibidos no bloco de upsell existente, então o módulo precisa estar ativado para que algo seja renderizado.

Adicionando o script

No Upcart, vá em Settings → Custom HTML → Scripts (before load) e cole o script abaixo. Substitua STRATEGY_ID e STRATEGY_API_KEY pelos valores do Aftersell e salve.

<script>
  const STRATEGY_ID = "YOUR_STRATEGY_ID";
  const STRATEGY_API_KEY = "YOUR_STRATEGY_API_KEY";
  const STRATEGY_BACKEND_URL = "https://start.aftersell.app";

  let cartToken = null;
  const fetchCartToken = async () => {
    const res = await fetch("/cart.js");
    const c = await res.json();
    cartToken = c.token;
  };

  const mapCartItemToContext = (cartItem) => ({
    productId: "gid://shopify/Product/" + cartItem.productId.toString(),
    variantId: "gid://shopify/ProductVariant/" + cartItem.variantId.toString(),
    tags: [],
    title: cartItem.title,
    vendor: cartItem.vendor,
    productType: cartItem.productType,
    handle: cartItem.handle,
    quantity: cartItem.quantity,
    price: cartItem.originalPrice / 100,
  });

  // --- StrategyProduct -> Upcart Product conversion -----------------------

  const gidToNumericId = (gid) => Number(String(gid).split("/").pop());
  const priceStringToCents = (price) =>
    price == null ? null : Math.round(parseFloat(price) * 100);

  const strategyMetafieldsToProductMetafields = (metafields = []) => {
    const grouped = {};
    for (const { namespace, key, value } of metafields) {
      grouped[namespace] = grouped[namespace] || {};
      grouped[namespace][key] = value;
    }
    return { product: grouped };
  };

  const deriveProductOptions = (variants = []) => {
    const byName = new Map();
    for (const variant of variants) {
      (variant.selectedOptions ?? []).forEach((opt, idx) => {
        if (!byName.has(opt.name)) {
          byName.set(opt.name, { name: opt.name, position: idx + 1, values: [] });
        }
        const entry = byName.get(opt.name);
        if (!entry.values.includes(opt.value)) entry.values.push(opt.value);
      });
    }
    return [...byName.values()];
  };

  const mapStrategyVariantToProductVariant = (variant) => {
    const selected = variant.selectedOptions ?? [];
    const optionValues = selected.map((o) => o.value);
    return {
      id: gidToNumericId(variant.variantId),
      title: variant.title,
      option1: optionValues[0] ?? null,
      option2: optionValues[1] ?? null,
      option3: optionValues[2] ?? null,
      sku: variant.sku ?? "",
      requires_shipping: true,
      taxable: true,
      featured_image: null,
      available: variant.availableForSale,
      name: variant.title,
      public_title: variant.title,
      options: optionValues,
      price: priceStringToCents(variant.price) ?? 0,
      weight: 0,
      compare_at_price: priceStringToCents(variant.compareAtPrice),
      inventory_management: "",
      barcode: null,
      requires_selling_plan: false,
      selling_plan_allocations: [],
    };
  };

  const mapStrategyProductToProduct = (product) => {
    const variants = (product.variants ?? []).map(mapStrategyVariantToProductVariant);
    const variantPrices = variants.map((v) => v.price);
    const priceMin = variantPrices.length ? Math.min(...variantPrices) : (priceStringToCents(product.price) ?? 0);
    const priceMax = variantPrices.length ? Math.max(...variantPrices) : (priceStringToCents(product.price) ?? 0);

    const variantCompareAtPrices = variants
      .map((v) => v.compare_at_price)
      .filter((p) => p != null);
    const compareAtMin = variantCompareAtPrices.length ? Math.min(...variantCompareAtPrices) : 0;
    const compareAtMax = variantCompareAtPrices.length ? Math.max(...variantCompareAtPrices) : 0;

    const images = (product.images ?? [])
      .slice()
      .sort((a, b) => a.position - b.position)
      .map((img) => img.src);

    return {
      id: gidToNumericId(product.productId),
      title: product.title,
      handle: product.handle,
      description: product.description ?? "",
      published_at: "",
      created_at: "",
      vendor: product.vendor ?? "",
      type: product.productType ?? "",
      tags: [...(product.tags ?? [])],
      price: priceStringToCents(product.price) ?? 0,
      price_min: priceMin,
      price_max: priceMax,
      available: product.availableForSale,
      price_varies: priceMin !== priceMax,
      compare_at_price: priceStringToCents(product.compareAtPrice),
      compare_at_price_min: compareAtMin,
      compare_at_price_max: compareAtMax,
      compare_at_price_varies: compareAtMin !== compareAtMax,
      variants,
      images,
      featured_image: images[0] ?? "",
      options: deriveProductOptions(product.variants),
      url: product.url ?? "",
      media: [],
      requires_selling_plan: false,
      selling_plan_groups: [],
      metafields: strategyMetafieldsToProductMetafields(product.metafields),
    };
  };

  // -----------------------------------------------------------------------

  let replacedUpsells = null;
  let lastFetchedCartSignature = null;

  const cartSignature = (cart) =>
    JSON.stringify(cart.items.map((i) => [i.variantId, i.quantity]));

  const runStrategyEvaluation = async () => {
    if (!STRATEGY_ID || !STRATEGY_API_KEY) return;

    await fetchCartToken();
    if (!cartToken) return;

    const cart = window.upcartGetCart();
    if (!cart) return;

    const signature = cartSignature(cart);
    if (signature === lastFetchedCartSignature) return;
    lastFetchedCartSignature = signature;

    const cartContext = {
      subtotal: cart.total_price / 100,
      itemCount: cart.items.reduce((acc, item) => acc + item.quantity, 0),
      lineCount: cart.items.length,
    };

    const products = cart.items.map(mapCartItemToContext);

    const res = await fetch(STRATEGY_BACKEND_URL + "/api/public/strategy/evaluate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Strategy-Api-Key": STRATEGY_API_KEY,
      },
      body: JSON.stringify({
        shopDomain: window.Shopify.shop,
        strategyId: STRATEGY_ID,
        context: {
          products,
          cartToken,
          cart: cartContext.itemCount > 0 ? cartContext : undefined,
          session: { currencyCode: window.Shopify.currency.active },
        },
      }),
    });
    replacedUpsells = await res.json();

    if (typeof window.upcartRefreshCart === "function") {
      window.upcartRefreshCart();
    }
  };

  window.upcartSubscribeCartUpdated(runStrategyEvaluation);

  const waitForUpcartCart = (timeoutMs = 10000) =>
    new Promise((resolve) => {
      const start = Date.now();
      const check = () => {
        if (window.upcartGetCart()) return resolve(true);
        if (Date.now() - start > timeoutMs) return resolve(false);
        setTimeout(check, 100);
      };
      check();
    });

  waitForUpcartCart().then((ready) => {
    if (ready) runStrategyEvaluation();
  });

  window.upcartModifyListOfUpsells = () => {
    if (!replacedUpsells || !Array.isArray(replacedUpsells.products)) return;
    try {
      return replacedUpsells.products.map(mapStrategyProductToProduct);
    } catch (err) {
      console.error("upcartModifyListOfUpsells mapping failed", err);
      return;
    }
  };
</script>

Sua chave de API da Strategy autoriza chamadas às Strategies da sua loja. O script acima a coloca em código do lado do cliente, que é a única maneira prática de invocar a API a partir do cart drawer. Trate a chave como trataria qualquer outra credencial pública da vitrine e rotacione-a no Aftersell em Settings → Product Strategy se ela for exposta de uma forma que você não pretendia.

O que a Strategy enxerga

Como isso é executado a partir do carrinho da vitrine, o contexto é um subconjunto reduzido do que está disponível nas superfícies nativas do Aftersell:

Contexto de produto

Os itens de linha atualmente no carrinho do Upcart são enviados como produtos de entrada. Gatilhos como tipo de produto, fornecedor, handle do produto, título do produto e quaisquer gatilhos de ID de produto / ID de variante são todos avaliados com base nesses itens.

Contexto do carrinho

Subtotal - subtotal do carrinho nas unidades principais da moeda da loja (por exemplo, dólares). O total_price do Upcart está em unidades menores (centavos), então o script divide por 100 para corresponder às unidades que o restante da API de Strategies usa - e às unidades em que suas regras de cart_subtotal são escritas.
Contagem de itens - quantidade total em todas as linhas.
Contagem de linhas - número de itens de linha distintos.

Contexto de sessão

Código de moeda - obtido de window.Shopify.currency.active.

Gatilhos de cliente e gatilhos UTM não corresponderão. O script padrão não envia tags de cliente, contagem de pedidos, localização nem parâmetros UTM - portanto, qualquer regra que use esses gatilhos nunca será acionada. Use gatilhos de produto, carrinho e moeda, ou um Catch all, para garantir que algo sempre seja retornado.

O que acontece quando a Strategy retorna

Os produtos retornados pela Strategy substituem completamente a lista que o Upcart exibiria no módulo Upsells. A lista de upsells definida pelo lojista é sobrescrita durante aquele carrinho - ela não é mesclada. Cada produto da Strategy é mapeado para o formato de produto esperado pelo Upcart (variantes, imagens, opções, metafields etc.), de modo que ele é renderizado dentro do bloco de upsell exatamente como qualquer outro produto.

Quando nenhum produto é retornado

Se a Strategy não retornar produtos, o módulo Upsells é renderizado vazio - nenhum upsell é exibido. Para evitar isso, configure um Catch all na Strategy para que sempre haja um produto de fallback para retornar. Consulte a página Criando Strategies para saber como configurar um Catch all.

Reavaliação nas mudanças do carrinho

Diferentemente dos upsells de checkout, a implementação do Upcart reavalia a Strategy toda vez que o carrinho muda - itens adicionados, removidos ou com quantidade atualizada. O script se inscreve no evento cartUpdated do Upcart, envia o novo carrinho para a API de Strategies e atualiza o cart drawer com a nova lista de upsells. Uma verificação de assinatura do carrinho pula chamadas redundantes se os itens de linha e as quantidades não tiverem realmente mudado, então eventos de carrinho consecutivos que não alteram o carrinho de forma significativa não acionarão a API novamente.

Dicas para Strategies do Upcart

Projete com base no carrinho. Gatilhos de formato do carrinho e de produto são os sinais mais fortes que você tem aqui. Histórico do cliente e segmentação baseada em UTM não são enviados pelo script padrão.
Use o Catch all como rede de segurança. Sem ele, o módulo Upsells não exibirá nada quando nenhuma regra corresponder.
Amigável a cache por padrão. A proteção de assinatura do carrinho evita acionar a API novamente se o carrinho não mudou de forma significativa - bom para compradores que abrem e fecham o carrinho sem editá-lo.

Primeiros passos

Página inicial

Melhores práticas

Upsells pós-compra

Carrinho Aftersell

Upsells no checkout (Shopify Plus)

Página de agradecimento

Upsells na página de produto

Rokt Thanks

Estratégias

Análises e rastreamento

Integrações

Aftersell MCP

Faturamento e conta

Solução de problemas

Visão geral

O que você vai precisar

Adicionando o script

O que a Strategy enxerga

Contexto de produto

Contexto do carrinho

Contexto de sessão

O que acontece quando a Strategy retorna

Quando nenhum produto é retornado

Reavaliação nas mudanças do carrinho

Dicas para Strategies do Upcart

​Visão geral

​O que você vai precisar

​Adicionando o script

​O que a Strategy enxerga

​Contexto de produto

​Contexto do carrinho

​Contexto de sessão

​O que acontece quando a Strategy retorna

​Quando nenhum produto é retornado

​Reavaliação nas mudanças do carrinho

​Dicas para Strategies do Upcart

Visão geral

O que você vai precisar

Adicionando o script

O que a Strategy enxerga

Contexto de produto

Contexto do carrinho

Contexto de sessão

O que acontece quando a Strategy retorna

Quando nenhum produto é retornado

Reavaliação nas mudanças do carrinho

Dicas para Strategies do Upcart