Overzicht

De Cart SDK is een JavaScript-API voor de Aftersell Cart op je storefront. Hiermee kun je het gedrag van de winkelwagen aanpassen, reageren op wat shoppers doen en de inhoud van de winkelwagen vanuit code lezen of wijzigen. Je voert SDK-code uit via Custom scripts, of via de React-modus van een Custom code block voor een block dat zijn eigen UI rendert.

Veel van wat merchants aan de SDK vragen, is al een instelling. Controleer voordat je een script schrijft of een cart block, voorwaarden per markt/land/valuta of een winkelwagen-instelling het al doet. Die blijven werken bij herontwerpen van de winkelwagen, en je script mogelijk niet.

Het globale toegangspunt

Alles hangt aan één global:

window.aftersell.cart

Elk snippet in deze docs schrijft window.aftersell.cart volledig uit, zodat elk snippet op zichzelf werkt wanneer je het plakt. Het één keer aliassen (const cart = window.aftersell.cart;) en daarna cart gebruiken is ook prima geldig, en veilig zelfs voordat de winkelwagen laadt. Vergeet alleen niet die regel op te nemen als je een snippet inkort, want een kale cart op zichzelf gooit cart is not defined.

Vier onderdelen doen het werk:

Configure

Stel in hoe de winkelwagen zich gedraagt: wanneer de drawer opent, hoe geldbedragen worden geformatteerd, of Aftersell add-to-cart onderschept.

Events

Reageer op wat er gebeurt: de winkelwagen is geladen, een item is toegevoegd, de drawer is geopend, er is op checkout geklikt.

Actions

Lees en wijzig de winkelwagen: open hem, voeg een item toe, werk een aantal bij, lees de huidige status.

Hooks

Wijzig hoe de winkelwagen zelf werkt: verberg of herlabel regels, herschik ze, koppel extra data, beheer add-to-cart.

Als een script van jou is gestopt met afgaan bij add-to-cart, begin dan bij Add-to-cart-interceptie. Daar wordt uitgelegd waarom Aftersell de toevoeging overneemt, en elke manier om een formulier af te melden.

Plus drie kleinere leden:

Lid	Waar het voor is
`ready()`	Een Promise die resolvet zodra de winkelwagen voor het eerst is geladen.
`context`	Server-gerenderde kopercontext, synchroon leesbaar.
`shadowRoot`	De shadow root van de winkelwagen, om elementen binnen de drawer te bevragen.

Events, actions of hooks?

De drie zijn makkelijk te verwarren, en de verkeerde kiezen is de meest voorkomende reden dat een script niet doet wat de auteur verwachtte:

Je wilt…	Gebruik	Voorbeeld
Code uitvoeren wanneer iets gebeurt	Event	Een analytics-event versturen wanneer een item wordt toegevoegd.
Wijzigen wat er in de winkelwagen zit	Action	Een gratis cadeau toevoegen zodra het totaal boven de $50 komt.
Wijzigen hoe de winkelwagen werkt of rendert	Hook	Gratis-cadeauregels verbergen in de drawer.

Het onderscheid dat het meest telt: een action wijzigt de daadwerkelijke winkelwagen van de shopper (en het totaal), terwijl een hook alleen wijzigt wat er gerenderd wordt. Een regel verbergen met een hook laat hem in de winkelwagen en in het totaal staan; hem verwijderen met een action haalt hem er echt uit.

Hoe en wanneer het laadt

De winkelwagen laadt in twee fasen, en de SDK is zo gebouwd dat je niet over volgorde hoeft na te denken:

Een kleine stub maakt window.aftersell.cart onmiddellijk aan, zodat die er altijd is.
De volledige SDK laadt kort daarna en neemt het over, waarbij de stub ter plekke wordt geüpgraded, zodat een eerder vastgelegde referentie blijft werken.

Dat geeft je twee categorieën aanroepen:

Set-up-aanroepen: direct veilig

configure(...), events.on(...) en elke hooks.register*-aanroep. Gebufferd vóór het opstarten en op volgorde opnieuw afgespeeld zodra de SDK laadt. Zet ze bovenaan je script.

Actions: wacht op ready()

Alles onder actions.*. Voer ze uit binnen ready() of een event handler. Te vroeg aangeroepen geven ze een waarschuwing in de console en doen ze niets, op een veilige manier: de asynchrone resolven alsnog, dus een .then()-keten breekt niet.

// 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() geeft een Promise terug die resolvet zodra de eerste winkelwagen-load is afgerond. Hij resolvet zowel bij falen als bij succes, zodat een shopper met een haperende verbinding je script nooit laat hangen. Controleer getCart() op null in plaats van aan te nemen dat er een winkelwagen is binnengekomen. ready() aanroepen nadat de winkelwagen al geladen is, resolvet onmiddellijk, dus het is veilig te gebruiken als algemene “de winkelwagen bestaat nu”-poort waar dan ook in je code.

Je hebt ready() niet nodig binnen een event handler. Tegen de tijd dat cart_loaded, cart_updated of item_added afgaat, is de winkelwagen geladen en zijn actions veilig aan te roepen.

context

window.aftersell.cart.context bevat koperdata die door de server is gerenderd, synchroon leesbaar, zonder dat ready() nodig is. Gebruik het voor markt- of landvertakkingen die moeten plaatsvinden voordat de winkelwagen laadt.

Veld	Beschrijving	Beschikbaar vóór het opstarten
`shopify_market`	De Shopify-markt van de koper.	Ja
`customer_country`	Tweeletterige landcode.	Ja
`customer_currency`	Actieve valutacode.	Ja
`money_format`	Het Shopify-geldformaat van de winkel.	Ja
`backend_url`	Directe backend-host, gebruikt als fallback wanneer de app proxy niet is geconfigureerd.	Ja
`storefront_access_token`	Token voor Storefront API-aanroepen.	Nee — toegevoegd wanneer de winkelwagen opstart

storefront_access_token is het ene context-veld dat de server niet in cart.context rendert. Het wordt aan context toegevoegd wanneer de winkelwagen opstart, dus als je het bovenaan je script leest, krijg je undefined. Await eerst window.aftersell.cart.ready().

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

Om verschillende block-instellingen per markt, land of valuta te tonen, gebruik je in plaats daarvan voorwaarden in de cart editor. Geen script nodig. De volledige Conditions-UI is vandaag beschikbaar op Rewards.

shadowRoot

De winkelwagen rendert binnen een shadow root, dus document.querySelector kan niets binnen de drawer zien. Om een element in de winkelwagen te bereiken, bevraag je de shadow root:

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

Richt je op dezelfde publieke cart-external-*-classes die Custom CSS gebruikt. Dat zijn de ondersteunde aanknopingspunten. De cart-internal-*-tegenhangers zijn het interne leidingwerk van de winkelwagen, dus bevraag in plaats daarvan de externe.

Grijp alleen naar de shadow root wanneer geen block, instelling of hook het werk doet. Een hook overleeft een herontwerp van de winkelwagen; een DOM-query is een onderhoudsprobleem voor jouw code.

De shadow root is er pas zodra de winkelwagen is opgestart, dus lees hem binnen ready() of een event handler in plaats van bovenaan je script.

Debugging

Een kapot script mag nooit add-to-cart of de drawer platleggen, dus de SDK vangt fouten op in plaats van ze te laten doorborrelen. Waar een fout zichtbaar wordt, hangt af van wat er kapot ging:

Wat er misging	Waar het verschijnt
Je script gooide een fout op het hoogste niveau	`console.error`, met vermelding van de regel en wat nooit is uitgevoerd
Een event handler gooide een fout	`console.error`; de andere handlers draaien nog steeds
Een hook gooide een fout	Stil. Gaat naar het debugkanaal hieronder
Een action draaide voordat de winkelwagen laadde	`console.warn`; de aanroep doet niets

Wanneer je script een fout gooit

Een custom script stopt bij de eerste fout, dus elke configure, events.on en hooks.register* onder die regel wordt nooit uitgevoerd. De winkelwagen zegt dat expliciet:

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

Dat is het bericht om naar te zoeken wanneer een handler die je zeker weten hebt geregistreerd nooit afgaat: hij is waarschijnlijk nooit bereikt. Het regelnummer is het top-level statement waar de uitvoering stopte, niet de innerlijke functie die de fout gooide, en het wordt weggelaten in plaats van gegokt als de stack van de browser niet bruikbaar is. Je scripts draaien ook onder hun eigen bestandsnamen, dus ze verschijnen als aftersell-cart-init.js en aftersell-cart-cart-update.js in DevTools. Je kunt ze openen vanuit het Sources-paneel en breakpoints instellen zoals bij elk ander bestand.

Het debugkanaal

Hookfouten worden bewust van de console weggehouden zodat shoppers ze nooit zien. Ze gaan in plaats daarvan hierheen:

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

Waar je verder kunt kijken

Configure

Elke optie, met elk een voorbeeld.

Events

Elk event, wanneer het afgaat en wat je niet moet doen in een handler.

Actions

Elke action, met elk een snippet.

Hooks

Elke hook, en hoe registraties samenwerken.

Cart object

De vorm van de winkelwagen en zijn regels.

Use cases

Complete, uitvoerbare oplossingen voor veelvoorkomende verzoeken.

Aan de slag

Startpagina

Best practices

Post-purchase upsells

Winkelwagen

Checkout-upsells (Shopify Plus)

Bedankpagina

Upsells op de productpagina

Rokt Thanks

Strategieën

Analytics en tracking

Integraties

Aftersell MCP

Facturering en account

Probleemoplossing

Het globale toegangspunt

Configure

Events

Actions

Hooks

Events, actions of hooks?

Hoe en wanneer het laadt

Set-up-aanroepen: direct veilig

Actions: wacht op ready()

ready()

context

shadowRoot

Debugging

Wanneer je script een fout gooit

Het debugkanaal

Waar je verder kunt kijken

Configure

Events

Actions

Hooks

Cart object

Use cases

​Het globale toegangspunt

Configure

Events

Actions

Hooks

​Events, actions of hooks?

​Hoe en wanneer het laadt

Set-up-aanroepen: direct veilig

Actions: wacht op ready()

​ready()

​context

​shadowRoot

​Debugging

​Wanneer je script een fout gooit

​Het debugkanaal

​Waar je verder kunt kijken

Configure

Events

Actions

Hooks

Cart object

Use cases

Het globale toegangspunt

Events, actions of hooks?

Hoe en wanneer het laadt

ready()

context

shadowRoot

Debugging

Wanneer je script een fout gooit

Het debugkanaal

Waar je verder kunt kijken