Upselle Upcart

Przegląd

Upcart to osobna aplikacja od Aftersell, więc Strategie nie są wbudowane w moduł Upsells w taki sposób, jak w przepływach post-purchase i checkoutu Aftersell. Zamiast tego łączysz obie aplikacje niewielkim skryptem, który wywołuje bezpośrednio Strategies API i przekazuje wynik do istniejącego modułu Upsells Upcart za pośrednictwem publicznego API Upcart. Skrypt jest gotowy do wklejenia — wklej go raz do niestandardowego HTML Upcart, zastąp dwie wartości (swój klucz API Strategii i ID Strategii), a moduł Upsells zacznie pokazywać produkty zwracane przez Strategię.

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.
Włączony moduł Upsells w Upcart. Skrypt nadpisuje listę produktów pokazywanych w istniejącym bloku upsell, więc moduł musi być włączony, aby cokolwiek się wyrenderowało.

Dodawanie skryptu

W Upcart przejdź do Settings → Custom HTML → Scripts (before load) i wklej poniższy skrypt. Zastąp STRATEGY_ID i STRATEGY_API_KEY wartościami z Aftersell, a następnie zapisz.

<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>

Twój klucz API Strategii autoryzuje wywołania Strategii Twojego sklepu. Powyższy skrypt umieszcza go w kodzie po stronie klienta, co jest jedynym praktycznym sposobem wywołania API z poziomu cart drawer. Traktuj klucz tak, jak każde inne 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ś.

Co widzi Strategia

Ponieważ działa to z poziomu koszyka w witrynie sklepu, kontekst jest okrojonym podzbiorem tego, co jest dostępne na natywnych powierzchniach Aftersell:

Kontekst produktu

Pozycje znajdujące się aktualnie w koszyku Upcart są wysyłane jako produkty wejściowe. Wyzwalacze takie jak typ produktu, dostawca, handle produktu, tytuł produktu oraz wszelkie wyzwalacze oparte na ID produktu / ID wariantu są oceniane względem tych pozycji.

Kontekst koszyka

Suma częściowa — suma częściowa koszyka w głównych jednostkach waluty sklepu (np. w dolarach). total_price w Upcart jest wyrażone w jednostkach podrzędnych (centach), więc skrypt dzieli je przez 100, aby dopasować jednostki używane przez resztę Strategies API — i jednostki, w których tworzone są Twoje reguły cart_subtotal.
Liczba sztuk — łączna liczba sztuk we wszystkich pozycjach.
Liczba pozycji — liczba odrębnych pozycji.

Kontekst sesji

Kod waluty — pobierany z window.Shopify.currency.active.

Wyzwalacze klienta i wyzwalacze UTM nie zostaną dopasowane. Domyślny skrypt nie wysyła tagów klienta, liczby zamówień, lokalizacji ani parametrów UTM — więc żadna reguła używająca tych wyzwalaczy nigdy nie zadziała. Używaj wyzwalaczy produktowych, koszykowych i walutowych albo Catch all, aby zawsze coś było zwracane.

Co się dzieje, gdy Strategia zwraca wynik

Produkty zwrócone przez Strategię całkowicie zastępują listę, którą Upcart w przeciwnym razie pokazałby w module Upsells. Lista upselli zdefiniowana przez sprzedawcę jest nadpisywana na czas trwania tego koszyka — nie jest scalana. Każdy produkt Strategii jest mapowany na oczekiwany przez Upcart kształt produktu (warianty, obrazy, opcje, metapola itd.), dzięki czemu renderuje się w bloku upsell dokładnie tak, jak każdy inny produkt.

Gdy żaden produkt nie zostanie zwrócony

Jeśli Strategia nie zwraca produktów, moduł Upsells renderuje się pusty — żadne upselle nie są pokazywane. Aby tego uniknąć, 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.

Ponowna ocena przy zmianach koszyka

W przeciwieństwie do upselli w checkoucie implementacja Upcart ponownie ocenia Strategię za każdym razem, gdy koszyk się zmienia — po dodaniu, usunięciu lub zmianie ilości produktów. Skrypt subskrybuje zdarzenie cartUpdated Upcart, wysyła nowy koszyk do Strategies API i odświeża cart drawer z nową listą upselli. Kontrola sygnatury koszyka pomija zbędne wywołania, jeśli pozycje i ilości faktycznie się nie zmieniły, więc następujące po sobie zdarzenia koszyka, które nie zmieniają go w istotny sposób, nie odpytają API ponownie.

Wskazówki dotyczące Strategii Upcart

Projektuj wokół koszyka. Wyzwalacze oparte na kształcie koszyka i produktach to najsilniejsze sygnały, jakie masz w tym miejscu. Historia klienta i targetowanie oparte na UTM nie są wysyłane przez domyślny skrypt.
Używaj Catch all jako zabezpieczenia. Bez niego moduł Upsells nie pokaże nic, gdy żadna reguła nie zostanie dopasowana.
Domyślnie przyjazny dla pamięci podręcznej. Ochrona sygnaturą koszyka zapobiega ponownemu wywoływaniu API, jeśli koszyk nie zmienił się w istotny sposób — to dobre dla kupujących, którzy otwierają i zamykają koszyk bez jego edytowania.

Pierwsze kroki

Strona główna

Najlepsze praktyki

Upselle po zakupie

Koszyk Aftersell

Upselle przy realizacji zakupu (Shopify Plus)

Strona z podziękowaniem

Upselle na stronie produktu

Rokt Thanks

Strategie

Analityka i śledzenie

Integracje

Aftersell MCP

Rozliczenia i konto

Rozwiązywanie problemów

Przegląd

Czego potrzebujesz

Dodawanie skryptu

Co widzi Strategia

Kontekst produktu

Kontekst koszyka

Kontekst sesji

Co się dzieje, gdy Strategia zwraca wynik

Gdy żaden produkt nie zostanie zwrócony

Ponowna ocena przy zmianach koszyka

Wskazówki dotyczące Strategii Upcart

​Przegląd

​Czego potrzebujesz

​Dodawanie skryptu

​Co widzi Strategia

​Kontekst produktu

​Kontekst koszyka

​Kontekst sesji

​Co się dzieje, gdy Strategia zwraca wynik

​Gdy żaden produkt nie zostanie zwrócony

​Ponowna ocena przy zmianach koszyka

​Wskazówki dotyczące Strategii Upcart

Przegląd

Czego potrzebujesz

Dodawanie skryptu

Co widzi Strategia

Kontekst produktu

Kontekst koszyka

Kontekst sesji

Co się dzieje, gdy Strategia zwraca wynik

Gdy żaden produkt nie zostanie zwrócony

Ponowna ocena przy zmianach koszyka

Wskazówki dotyczące Strategii Upcart