Überblick

Das Cart SDK ist eine JavaScript-API für den Aftersell Cart in deinem Storefront. Es lässt dich ändern, wie sich der Warenkorb verhält, auf das reagieren, was Käufer tun, und den Inhalt des Warenkorbs per Code lesen oder ändern. Du führst SDK-Code über benutzerdefinierte Scripts aus, oder über den React-Modus eines Custom-Code-Blocks für einen Block, der seine eigene UI rendert.

Vieles, was Händler vom SDK verlangen, ist bereits eine Einstellung. Prüfe vor dem Schreiben eines Scripts, ob ein Cart-Block, Bedingungen nach Markt/Land/Währung oder eine Cart-Einstellung es bereits erledigt. Die funktionieren auch nach Cart-Redesigns weiter, dein Script möglicherweise nicht.

Der globale Einstiegspunkt

Alles hängt an einem Global:

window.aftersell.cart

Jedes Snippet in diesen Docs schreibt window.aftersell.cart vollständig aus, sodass jedes für sich funktioniert, wenn du es einfügst. Es einmal zu aliasen (const cart = window.aftersell.cart;) und ab dann cart zu verwenden ist ebenfalls völlig valide und sogar sicher, bevor der Warenkorb lädt. Denk nur daran, diese Zeile einzufügen, wenn du ein Snippet kürzt, denn ein nacktes cart allein wirft cart is not defined.

Vier Teile erledigen die Arbeit:

Configure

Lege fest, wie sich der Warenkorb verhält: wann sich der Drawer öffnet, wie Geld formatiert wird, ob Aftersell Add-to-cart abfängt.

Events

Reagiere auf das, was passiert: der Warenkorb wurde geladen, ein Artikel hinzugefügt, der Drawer geöffnet, Checkout geklickt.

Actions

Lies und ändere den Warenkorb: öffne ihn, füge einen Artikel hinzu, aktualisiere eine Menge, lies den aktuellen Zustand.

Hooks

Ändere, wie der Warenkorb selbst funktioniert: Zeilen ausblenden oder umbenennen, neu ordnen, zusätzliche Daten anhängen, Add-to-cart steuern.

Wenn eines deiner Scripts beim Add-to-cart nicht mehr feuert, beginne bei Add-to-cart-Abfangen. Dort wird erklärt, warum Aftersell das Hinzufügen übernimmt, und jede Möglichkeit, ein Formular auszunehmen.

Plus drei kleinere Mitglieder:

Mitglied	Wofür es ist
`ready()`	Ein Promise, das aufgelöst wird, sobald der Warenkorb erstmals geladen hat.
`context`	Servergerenderter Käufer-Kontext, synchron lesbar.
`shadowRoot`	Der Shadow Root des Warenkorbs, um Elemente im Drawer abzufragen.

Events, Actions oder Hooks?

Die drei sind leicht zu verwechseln, und die falsche Wahl ist der häufigste Grund, warum ein Script nicht das tut, was sein Autor erwartet hat:

Du willst…	Verwende	Beispiel
Code ausführen, wenn etwas passiert	Event	Ein Analytics-Event senden, wenn ein Artikel hinzugefügt wird.
Ändern, was im Warenkorb ist	Action	Ein Gratisgeschenk hinzufügen, sobald die Summe $50 übersteigt.
Ändern, wie der Warenkorb funktioniert oder rendert	Hook	Gratisgeschenk-Zeilen im Drawer ausblenden.

Die wichtigste Unterscheidung: Eine Action ändert den tatsächlichen Warenkorb des Käufers (und seine Gesamtsumme), während ein Hook nur ändert, was gerendert wird. Eine Zeile mit einem Hook auszublenden lässt sie im Warenkorb und in der Gesamtsumme; sie mit einer Action zu entfernen nimmt sie wirklich heraus.

Wie und wann es lädt

Der Warenkorb lädt in zwei Phasen, und das SDK ist so gebaut, dass du nicht über die Reihenfolge nachdenken musst:

Ein kleiner Stub erstellt window.aftersell.cart sofort, sodass es immer da ist.
Das vollständige SDK lädt kurz danach und übernimmt, indem es den Stub an Ort und Stelle aufwertet — eine früher erfasste Referenz funktioniert also weiter.

Das ergibt zwei Kategorien von Aufrufen:

Setup-Aufrufe: sofort sicher

configure(...), events.on(...) und jeder hooks.register*-Aufruf. Werden vor dem Boot gepuffert und in Reihenfolge abgespielt, sobald das SDK lädt. Setze sie an den Anfang deines Scripts.

Actions: auf ready() warten

Alles unter actions.*. Führe sie innerhalb von ready() oder einem Event-Handler aus. Zu früh aufgerufen warnen sie in der Konsole und tun nichts — sicher: Die asynchronen lösen trotzdem auf, sodass eine .then()-Kette nicht bricht.

// 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() gibt ein Promise zurück, das aufgelöst wird, sobald das erste Laden des Warenkorbs abgeschlossen ist. Es wird sowohl bei Fehlschlag als auch bei Erfolg aufgelöst, sodass ein Käufer mit wackliger Verbindung dein Script nie hängen lässt. Prüfe getCart() auf null, statt anzunehmen, dass ein Warenkorb angekommen ist. Ein Aufruf von ready(), nachdem der Warenkorb bereits geladen ist, wird sofort aufgelöst — es ist also sicher, es überall in deinem Code als allgemeines „der Warenkorb existiert jetzt“-Gate zu verwenden.

Innerhalb eines Event-Handlers brauchst du ready() nicht. Wenn cart_loaded, cart_updated oder item_added ausgelöst wird, ist der Warenkorb geladen und Actions können sicher aufgerufen werden.

context

window.aftersell.cart.context enthält vom Server gerenderte Käuferdaten, synchron lesbar, ohne dass ready() nötig ist. Verwende es für Markt- oder Länder-Verzweigungen, die passieren müssen, bevor der Warenkorb lädt.

Feld	Beschreibung	Vor dem Boot verfügbar
`shopify_market`	Der Shopify-Markt des Käufers.	Ja
`customer_country`	Zweibuchstabiger Ländercode.	Ja
`customer_currency`	Aktiver Währungscode.	Ja
`money_format`	Das Shopify-Geldformat des Shops.	Ja
`backend_url`	Direkter Backend-Host, als Fallback, wenn der App-Proxy nicht konfiguriert ist.	Ja
`storefront_access_token`	Token für Storefront-API-Aufrufe.	Nein — wird hinzugefügt, wenn der Warenkorb bootet

storefront_access_token ist das eine context-Feld, das der Server nicht in cart.context rendert. Es wird context hinzugefügt, wenn der Warenkorb bootet — es am Anfang deines Scripts zu lesen ergibt also undefined. Warte zuerst auf window.aftersell.cart.ready().

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

Um unterschiedliche Block-Einstellungen nach Markt, Land oder Währung anzuzeigen, verwende stattdessen Bedingungen im Cart-Editor. Kein Script erforderlich. Die vollständige Conditions-UI gibt es heute bei Rewards.

shadowRoot

Der Warenkorb wird innerhalb eines Shadow Root gerendert, sodass document.querySelector nichts im Drawer sehen kann. Um ein Element im Warenkorb zu erreichen, frage den Shadow Root ab:

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

Ziele auf dieselben öffentlichen cart-external-*-Klassen, die auch Custom CSS verwendet. Das sind die unterstützten Griffe. Die cart-internal-*-Zwillinge sind die interne Verkabelung des Warenkorbs, frage also stattdessen die externen ab.

Greif nur zum Shadow Root, wenn kein Block, keine Einstellung und kein Hook die Aufgabe erledigt. Ein Hook überlebt ein Cart-Redesign; eine DOM-Abfrage muss dein Code selbst pflegen.

Der Shadow Root ist erst da, wenn der Warenkorb gebootet hat — lies ihn also innerhalb von ready() oder einem Event-Handler statt am Anfang deines Scripts.

Debugging

Ein defektes Script darf nie Add-to-cart oder den Drawer lahmlegen, deshalb hält das SDK Fehler zurück, statt sie nach oben durchzureichen. Wo ein Fehler auftaucht, hängt davon ab, was kaputtging:

Was fehlgeschlagen ist	Wo es erscheint
Dein Script warf auf oberster Ebene	`console.error`, mit der Zeile und dem, was nie lief
Ein Event-Handler warf	`console.error`; die anderen Handler laufen weiter
Ein Hook warf	Still. Landet im Debug-Kanal unten
Eine Action lief, bevor der Warenkorb geladen war	`console.warn`; der Aufruf tut nichts

Wenn dein Script wirft

Ein benutzerdefiniertes Script stoppt beim ersten Fehler, sodass jedes configure, events.on und hooks.register* unterhalb dieser Zeile nie läuft. Der Warenkorb sagt das explizit:

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

Das ist die Meldung, nach der du suchen solltest, wenn ein Handler, den du definitiv registriert hast, nie ausgelöst wird: Er wurde wahrscheinlich nie erreicht. Die Zeilennummer ist das Top-Level-Statement, an dem die Ausführung gestoppt hat, nicht die innere Funktion, die geworfen hat — und sie wird weggelassen statt geraten, wenn der Stack des Browsers nicht brauchbar ist. Deine Scripts laufen außerdem unter ihren eigenen Dateinamen und erscheinen daher als aftersell-cart-init.js und aftersell-cart-cart-update.js in den DevTools. Du kannst sie im Sources-Panel öffnen und Breakpoints setzen wie in jeder anderen Datei.

Der Debug-Kanal

Hook-Fehler werden bewusst aus der Konsole ferngehalten, damit Käufer sie nie sehen. Sie landen stattdessen hier:

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

Nächste Schritte

Configure

Jede Option, mit je einem Beispiel.

Events

Jedes Event, wann es ausgelöst wird und was du in einem Handler nicht tun solltest.

Actions

Jede Action, mit je einem Snippet.

Hooks

Jeder Hook und wie sich Registrierungen kombinieren.

Cart-Objekt

Die Struktur des Warenkorbs und seiner Zeilen.

Use Cases

Vollständige, lauffähige Lösungen für häufige Anforderungen.

Erste Schritte

Startseite

Best Practices

Post-Purchase-Upsells

Warenkorb

Checkout-Upsells (Shopify Plus)

Danke-Seite

Produktseiten-Upsells

Rokt Thanks

Strategien

Analytics & Tracking

Integrationen

Aftersell MCP

Abrechnung & Konto

Fehlerbehebung

Der globale Einstiegspunkt

Configure

Events

Actions

Hooks

Events, Actions oder Hooks?

Wie und wann es lädt

Setup-Aufrufe: sofort sicher

Actions: auf ready() warten

ready()

context

shadowRoot

Debugging

Wenn dein Script wirft

Der Debug-Kanal

Nächste Schritte

Configure

Events

Actions

Hooks

Cart-Objekt

Use Cases

​Der globale Einstiegspunkt

Configure

Events

Actions

Hooks

​Events, Actions oder Hooks?

​Wie und wann es lädt

Setup-Aufrufe: sofort sicher

Actions: auf ready() warten

​ready()

​context

​shadowRoot

​Debugging

​Wenn dein Script wirft

​Der Debug-Kanal

​Nächste Schritte

Configure

Events

Actions

Hooks

Cart-Objekt

Use Cases

Der globale Einstiegspunkt

Events, Actions oder Hooks?

Wie und wann es lädt

ready()

context

shadowRoot

Debugging

Wenn dein Script wirft

Der Debug-Kanal

Nächste Schritte