Przegląd

Cart SDK to interfejs JavaScript API dla koszyka Aftersell Cart w Twoim sklepie. Pozwala zmieniać zachowanie koszyka, reagować na działania kupujących oraz odczytywać lub zmieniać zawartość koszyka z poziomu kodu. Kod SDK uruchamiasz przez Skrypty niestandardowe lub przez tryb React bloku Custom code, jeśli blok ma renderować własny interfejs.

Wiele z tego, o co sprzedawcy proszą SDK, jest już dostępne jako ustawienie. Zanim napiszesz skrypt, sprawdź, czy blok koszyka, warunki według rynku/kraju/waluty lub ustawienie koszyka już to robi. One działają dalej po przeprojektowaniu koszyka, a Twój skrypt może przestać.

Globalny punkt wejścia

Wszystko opiera się na jednym obiekcie globalnym:

window.aftersell.cart

Każdy fragment kodu w tej dokumentacji zapisuje window.aftersell.cart w pełnej formie, więc każdy z nich działa samodzielnie po wklejeniu. Jednorazowe utworzenie aliasu (const cart = window.aftersell.cart;) i używanie dalej cart jest w pełni poprawne i bezpieczne nawet przed załadowaniem koszyka. Pamiętaj tylko, aby dołączyć tę linię, jeśli skracasz fragment, ponieważ samo cart bez niej rzuca błąd cart is not defined.

Pracę wykonują cztery części:

Configure

Ustaw zachowanie koszyka: kiedy otwiera się szuflada, jak formatowane są kwoty, czy Aftersell przechwytuje dodawanie do koszyka.

Events

Reaguj na to, co się dzieje: koszyk się załadował, dodano produkt, otwarto szufladę, kliknięto checkout.

Actions

Odczytuj i zmieniaj koszyk: otwórz go, dodaj produkt, zaktualizuj ilość, odczytaj bieżący stan.

Hooks

Zmieniaj sposób działania samego koszyka: ukrywaj lub zmieniaj etykiety pozycji, zmieniaj ich kolejność, dołączaj dodatkowe dane, kontroluj dodawanie do koszyka.

Jeśli któryś z Twoich skryptów przestał odpalać się przy add-to-cart, zacznij od Przechwytywania add-to-cart. Wyjaśnia, dlaczego Aftersell przejmuje dodawanie, i wszystkie sposoby, by wyłączyć z tego pojedynczy formularz.

Plus trzy mniejsze elementy:

Element	Do czego służy
`ready()`	Promise, który rozwiązuje się po pierwszym załadowaniu koszyka.
`context`	Renderowany po stronie serwera kontekst kupującego, dostępny synchronicznie.
`shadowRoot`	Shadow root koszyka, do wyszukiwania elementów wewnątrz szuflady.

Zdarzenia, akcje czy hooki?

Te trzy łatwo pomylić, a wybranie niewłaściwego to najczęstszy powód, dla którego skrypt nie robi tego, czego oczekiwał jego autor:

Chcesz…	Użyj	Przykład
Uruchomić kod gdy coś się wydarzy	Zdarzenie	Wyślij zdarzenie analityczne po dodaniu produktu.
Zmienić zawartość koszyka	Akcja	Dodaj darmowy prezent, gdy suma przekroczy $50.
Zmienić sposób działania lub renderowania koszyka	Hook	Ukryj pozycje z darmowymi prezentami w szufladzie.

Najważniejsza różnica: akcja zmienia rzeczywisty koszyk kupującego (i jego sumę), podczas gdy hook zmienia tylko to, co się renderuje. Ukrycie pozycji hookiem pozostawia ją w koszyku i w sumie; usunięcie jej akcją wyjmuje ją naprawdę.

Jak i kiedy się ładuje

Koszyk ładuje się w dwóch etapach, a SDK jest zbudowane tak, abyś nie musiał myśleć o kolejności:

Mały stub tworzy window.aftersell.cart natychmiast, więc obiekt zawsze istnieje.
Pełne SDK ładuje się chwilę później i przejmuje kontrolę, ulepszając stub w miejscu, więc wcześniej zapisana referencja nadal działa.

Daje to dwie kategorie wywołań:

Wywołania konfiguracyjne: bezpieczne od razu

configure(...), events.on(...) i każde wywołanie hooks.register*. Buforowane przed startem i odtwarzane w kolejności po załadowaniu SDK. Umieszczaj je na początku skryptu.

Akcje: poczekaj na ready()

Wszystko pod actions.*. Uruchamiaj je wewnątrz ready() lub obsługi zdarzenia. Wywołane zbyt wcześnie wypisują ostrzeżenie w konsoli i nic nie robią — bezpiecznie: te asynchroniczne i tak się rozwiązują, więc łańcuch .then() się nie zepsuje.

// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('Added', payload.item.title);
});

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});

ready()

ready() zwraca Promise, który rozwiązuje się, gdy pierwsze ładowanie koszyka się zakończy. Rozwiązuje się zarówno przy niepowodzeniu, jak i sukcesie, więc kupujący z niestabilnym połączeniem nigdy nie zostawi Twojego skryptu w zawieszeniu. Sprawdzaj, czy getCart() zwraca null, zamiast zakładać, że koszyk dotarł. Wywołanie ready() po tym, jak koszyk już się załadował, rozwiązuje się natychmiast, więc można go bezpiecznie używać jako ogólnej bramki „koszyk już istnieje” w dowolnym miejscu kodu.

Nie potrzebujesz ready() wewnątrz obsługi zdarzenia. Zanim wystrzeli cart_loaded, cart_updated lub item_added, koszyk jest już załadowany i akcje można bezpiecznie wywoływać.

context

window.aftersell.cart.context przechowuje dane kupującego renderowane przez serwer, dostępne synchronicznie, bez potrzeby ready(). Używaj go do rozgałęzień według rynku lub kraju, które muszą nastąpić przed załadowaniem koszyka.

Pole	Opis	Dostępne przed startem
`shopify_market`	Rynek Shopify kupującego.	Tak
`customer_country`	Dwuliterowy kod kraju.	Tak
`customer_currency`	Kod aktywnej waluty.	Tak
`money_format`	Format kwot Shopify sklepu.	Tak
`backend_url`	Bezpośredni host backendu, używany jako rezerwa, gdy app proxy nie jest skonfigurowane.	Tak
`storefront_access_token`	Token do wywołań Storefront API.	Nie — dodawany, gdy koszyk startuje

storefront_access_token to jedyne pole context, którego serwer nie renderuje do cart.context. Jest dodawane do context, gdy koszyk startuje, więc odczytanie go na początku skryptu zwraca undefined. Najpierw poczekaj na window.aftersell.cart.ready().

if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}

Aby pokazywać różne ustawienia bloków według rynku, kraju lub waluty, użyj zamiast tego warunków w edytorze koszyka. Skrypt nie jest potrzebny. Pełny interfejs warunków jest dziś dostępny w Rewards.

shadowRoot

Koszyk renderuje się wewnątrz shadow root, więc document.querySelector nie widzi niczego wewnątrz szuflady. Aby dosięgnąć elementu w koszyku, odpytaj shadow root:

const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');

Celuj w te same publiczne klasy cart-external-*, których używa Custom CSS. To są wspierane uchwyty. Bliźniacze klasy cart-internal-* to wewnętrzna maszyneria koszyka, więc odpytuj zamiast nich te zewnętrzne.

Sięgaj po shadow root tylko wtedy, gdy żaden blok, ustawienie ani hook nie wykonuje zadania. Hook przetrwa przeprojektowanie koszyka; zapytanie DOM to problem utrzymaniowy Twojego kodu.

Shadow root istnieje dopiero po starcie koszyka, więc odczytuj go wewnątrz ready() lub obsługi zdarzenia, a nie na początku skryptu.

Debugowanie

Zepsuty skrypt nigdy nie może wyłączyć dodawania do koszyka ani szuflady, dlatego SDK izoluje błędy, zamiast pozwalać im się rozprzestrzeniać. Miejsce, w którym błąd się ujawnia, zależy od tego, co się zepsuło:

Co zawiodło	Gdzie się to pokazuje
Twój skrypt rzucił błąd na najwyższym poziomie	`console.error`, ze wskazaniem linii i tego, co nigdy się nie uruchomiło
Obsługa zdarzenia rzuciła błąd	`console.error`; pozostałe obsługi nadal działają
Hook rzucił błąd	Cisza. Trafia do kanału debugowania poniżej
Akcja uruchomiona przed załadowaniem koszyka	`console.warn`; wywołanie nic nie robi

Gdy Twój skrypt rzuca błąd

Skrypt niestandardowy zatrzymuje się na pierwszym błędzie, więc każde configure, events.on i hooks.register* poniżej tej linii nigdy się nie uruchamia. Koszyk mówi o tym wprost:

[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.

To komunikat, którego należy szukać, gdy obsługa, którą na pewno zarejestrowano, nigdy nie odpala: prawdopodobnie nigdy nie została osiągnięta. Numer linii to instrukcja najwyższego poziomu, na której zatrzymało się wykonanie, a nie wewnętrzna funkcja, która rzuciła błąd; jest pomijany zamiast zgadywany, jeśli stos przeglądarki nie nadaje się do użytku. Twoje skrypty działają też pod własnymi nazwami plików, więc w DevTools pojawiają się jako aftersell-cart-init.js i aftersell-cart-cart-update.js. Możesz otworzyć je w panelu Sources i ustawiać punkty przerwania jak w każdym innym pliku.

Kanał debugowania

Błędy hooków są celowo trzymane z dala od konsoli, aby kupujący nigdy ich nie widzieli. Trafiają zamiast tego tutaj:

// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));

Co dalej

Configure

Każda opcja, z przykładem dla każdej.

Events

Każde zdarzenie, kiedy się odpala i czego nie robić w obsłudze.

Actions

Każda akcja, z fragmentem kodu dla każdej.

Hooks

Każdy hook i jak rejestracje się składają.

Obiekt koszyka

Struktura koszyka i jego pozycji.

Przypadki użycia

Kompletne, gotowe do uruchomienia rozwiązania częstych próśb.

Pierwsze kroki

Strona główna

Najlepsze praktyki

Upselle po zakupie

Koszyk

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

Globalny punkt wejścia

Configure

Events

Actions

Hooks

Zdarzenia, akcje czy hooki?

Jak i kiedy się ładuje

Wywołania konfiguracyjne: bezpieczne od razu

Akcje: poczekaj na ready()

ready()

context

shadowRoot

Debugowanie

Gdy Twój skrypt rzuca błąd

Kanał debugowania

Co dalej

Configure

Events

Actions

Hooks

Obiekt koszyka

Przypadki użycia

​Globalny punkt wejścia

Configure

Events

Actions

Hooks

​Zdarzenia, akcje czy hooki?

​Jak i kiedy się ładuje

Wywołania konfiguracyjne: bezpieczne od razu

Akcje: poczekaj na ready()

​ready()

​context

​shadowRoot

​Debugowanie

​Gdy Twój skrypt rzuca błąd

​Kanał debugowania

​Co dalej

Configure

Events

Actions

Hooks

Obiekt koszyka

Przypadki użycia

Globalny punkt wejścia

Zdarzenia, akcje czy hooki?

Jak i kiedy się ładuje

ready()

context

shadowRoot

Debugowanie

Gdy Twój skrypt rzuca błąd

Kanał debugowania

Co dalej