Skip to main content
Mit benutzerdefinierten Scripts kannst du dein eigenes JavaScript über das Cart SDK gegen den Warenkorb ausführen. Füge sie im Cart-Editor unter Cart settings → Custom script hinzu, wo ein Dropdown zwischen zwei Slots umschaltet: Initialization und On cart update. Schreibe in diesen Editoren reines JavaScript, ohne <script>-Tags. On cart update hat eine Reset to default-Aktion, die die Starter-Vorlage wiederherstellt; Initialization nicht – bewahre also eine eigene Kopie auf, bevor du den Slot leerst.
Vieles, wofür Händler früher Scripts geschrieben haben, ist heute eine integrierte Einstellung. Sieh dir zuerst Bevor du ein Script schreibst an: Eine Einstellung funktioniert auch nach Cart-Redesigns weiter, dein Script möglicherweise nicht.

Welcher Slot ist der richtige

Initialization

Das Initialization-Script läuft einmal, wenn der Warenkorb lädt. Es ist dein Einstiegspunkt, um alles einzurichten: das Warenkorb-Verhalten konfigurieren, Events abonnieren und Hooks registrieren. Das SDK ist als window.aftersell.cart verfügbar. Setup-Aufrufe, die du hier machst (configure(...), events.on(...), hooks.*), kannst du sicher am Anfang des Scripts aufrufen, noch bevor der Warenkorb vollständig hochgefahren ist; sie werden gepuffert und angewendet, sobald das passiert. Aktionen, die den Warenkorb lesen oder ändern (wie addItem oder getCart), sollten innerhalb von ready() oder eines Event-Handlers laufen. Der Slot startet mit drei auskommentierten Beispielen – den Drawer bei jedem Hinzufügen öffnen, auf cart_loaded reagieren und Gratisgeschenk-Zeilen ausblenden –, sodass ein unverändertes Initialization-Script nichts tut. Kommentiere eines ein, um es auszuprobieren, oder ersetze sie. Die natürliche Form für diesen Slot ist eine einmalige Registrierung ohne beteiligte Events: Registriere das Verhalten einmal und lass den Warenkorb es ab dann anwenden. Gratisgeschenk-Zeilen im Drawer auszublenden, ohne die Gesamtsumme zu ändern, ist das mitgelieferte Beispiel dafür:
registerLineTransform läuft für jede Zeile, während sie gerendert wird, und setHidden betrifft nur die Anzeige – die Zeile bleibt also im Warenkorb und zählt weiterhin zur Gesamtsumme, sie wird nur nicht im Drawer angezeigt. Sieh dir Warenkorb-Zeilen ausblenden und umbenennen an, um mehr über die Möglichkeiten einer Transformation zu erfahren. Aktionen, die den Warenkorb lesen, gehören in ready():
Der Zugriff auf das DOM des Warenkorbs erfordert dieselbe Wartezeit und braucht shadowRoot: Der Warenkorb wird innerhalb eines Shadow Root gerendert, sodass document.querySelector nichts im Drawer sehen kann.
Du willst vor dem Laden des Warenkorbs nach Markt, Land oder Währung verzweigen? Lies stattdessen context. Es ist synchron verfügbar, ganz ohne ready(), sodass du das Registrieren von Handlern für Käufer, auf die eine Regel nicht zutrifft, komplett überspringen kannst.

On cart update

Das On cart update-Script läuft bei jeder Änderung des Warenkorbs. Es ist ein gesperrter Wrapper um ein cart_updated-Abonnement – du bearbeitest also nur den Body, und dein Code erhält den aktualisierten cart. Dieser Slot ist für Regeln, die bei jeder Warenkorb-Änderung neu ausgewertet werden müssen. Ein Gratisgeschenk-Schwellenwert ist der klassische Fall (gib $75 aus, erhalte eine Gratis-Tasche), weil die Antwort vom aktuellen Inhalt abhängt und dir nichts anderes mitteilen kann, wann er sich ändert:

Den Warenkorb in einem gewünschten Zustand halten

Die Zeile if (shouldHaveGift === hasGift) return; macht das Ganze sicher, und sie lässt sich auf jedes Script verallgemeinern, das den Warenkorb in einem gewünschten Zustand hält. Dieser Slot reagiert sowohl auf Warenkorb-Änderungen als auch verursacht sie, sodass jedes addItem oder removeItem ihn erneut auslöst. Beschreibe den Zustand, den du willst, vergleiche ihn mit dem Zustand, den du hast, und kehre frühzeitig zurück, wenn sie bereits übereinstimmen – so konvergiert der Handler nach einem Durchlauf, statt in eine Schleife zu geraten. Sieh dir die zwei Regeln an, um die ungeschützte Variante zu sehen, die du vermeiden solltest, und warum die Payload schreibgeschützt ist. In einem langsameren Shop lohnt sich außerdem ein In-Flight-Flag auf Modulebene, damit zwei schnelle Änderungen nicht beide ein Hinzufügen starten können, bevor das erste abgeschlossen ist.
cart_updated wird nur bei Änderungen nach dem ersten Laden ausgelöst (Event-Timing), sodass ein Script in diesem Slot einen Warenkorb, der beim Laden der Seite bereits qualifiziert ist, nicht abgleicht. Für eine Version, die beides abdeckt, abonniere cart_loaded und cart_updated mit derselben Funktion aus dem Initialization-Slot. Siehe Ein Gratisgeschenk ab einem Schwellenwert automatisch hinzufügen.

Wenn ein Script fehlschlägt

Jeder Slot läuft in seiner eigenen Sandbox, sodass ein defektes Initialization-Script die Ausführung von On cart update nicht verhindern kann – und keines von beiden kann den Warenkorb selbst zum Absturz bringen. Innerhalb eines Slots stoppt die Ausführung jedoch beim ersten Fehler. Alles unterhalb dieser Zeile wird übersprungen, was bedeutet, dass jedes configure, events.on oder hooks.register* weiter unten nie registriert wird. Das ist die übliche Erklärung für „mein Handler wird nie ausgelöst“, obwohl der Code richtig aussieht. Der Warenkorb nennt die fehlerhafte Zeile in der Browser-Konsole, und jeder Slot läuft unter seinem eigenen Dateinamen (aftersell-cart-init.js und aftersell-cart-cart-update.js), sodass du beide im Sources-Panel der DevTools öffnen und Breakpoints setzen kannst. Siehe Debugging für die genauen Meldungen und für den Debug-Kanal, der Hook-Fehler abfängt, die nicht in der Konsole erscheinen. Da cart_loaded für späte Abonnenten erneut abgespielt wird, spielt die Registrierungsreihenfolge nie eine Rolle. Die sicherste Struktur ist, zuerst alles zu registrieren und die riskante Arbeit innerhalb von Handlern zu erledigen, wo ein Throw auf diesen Handler beschränkt bleibt.

Nächste Schritte

  • Cart SDK: Benutzerdefinierte Scripts sind der Weg, SDK-Code auszuführen. Sieh dir die Referenzen zu configure, Events, Actions und Hooks für die gesamte Oberfläche an, das Cart-Objekt für die Struktur dessen, was Handler erhalten, und die Use Cases für fertige Snippets.
  • Custom-Code-Blöcke: zum Hinzufügen von Markup zum Warenkorb. Beachte, dass der HTML-Modus des Custom-Code-Blocks kein JavaScript ausführt; verwende für Logik benutzerdefinierte Scripts (oder den React-Modus des Blocks).