Skip to main content
Le Cart SDK est une API JavaScript pour le panier Aftersell sur votre boutique. Il vous permet de modifier le comportement du panier, de réagir aux actions des acheteurs et de lire ou modifier le contenu du panier depuis du code. Vous exécutez du code SDK via les Scripts personnalisés, ou via le mode React d’un bloc Custom code pour un bloc qui affiche sa propre interface.
Beaucoup de ce que les marchands demandent au SDK est déjà un paramètre. Avant d’écrire un script, vérifiez si un bloc de panier, des conditions par marché/pays/devise ou un paramètre de panier le fait déjà. Ceux-ci continuent de fonctionner à travers les refontes du panier, ce qui n’est pas forcément le cas de votre script.

Le point d’entrée global

Tout part d’un seul global :
Chaque extrait de cette documentation écrit window.aftersell.cart en entier, afin que chacun d’eux fonctionne seul quand vous le collez. Créer un alias une fois (const cart = window.aftersell.cart;) et utiliser cart ensuite est parfaitement valide aussi, et sûr même avant le chargement du panier. Pensez simplement à inclure cette ligne si vous raccourcissez un extrait, car un cart nu tout seul lève cart is not defined.
Quatre parties font le travail :

Configure

Définissez le comportement du panier : quand le tiroir s’ouvre, comment les montants sont formatés, si Aftersell intercepte l’ajout au panier.

Events

Réagissez à ce qui se passe : le panier s’est chargé, un article a été ajouté, le tiroir s’est ouvert, le paiement a été cliqué.

Actions

Lisez et modifiez le panier : ouvrez-le, ajoutez un article, mettez à jour une quantité, lisez l’état actuel.

Hooks

Modifiez le fonctionnement du panier lui-même : masquez ou renommez des lignes, réordonnez-les, attachez des données supplémentaires, contrôlez l’ajout au panier.
Si un de vos scripts a cessé de se déclencher à l’ajout au panier, commencez par Interception de l’ajout au panier. Elle explique pourquoi Aftersell prend en charge l’ajout, et toutes les façons de désinscrire un formulaire.
Plus trois membres plus modestes :

Événements, actions ou hooks ?

Les trois sont faciles à confondre, et choisir le mauvais est la raison la plus courante pour laquelle un script ne fait pas ce que son auteur attendait : La distinction la plus importante : une action change le panier réel de l’acheteur (et son total), tandis qu’un hook ne change que ce qui s’affiche. Masquer une ligne avec un hook la laisse dans le panier et dans le total ; la retirer avec une action la supprime pour de bon.

Comment et quand il se charge

Le panier se charge en deux étapes, et le SDK est conçu pour que vous n’ayez pas à penser à l’ordre :
  1. Un petit stub crée window.aftersell.cart immédiatement, il est donc toujours présent.
  2. Le SDK complet se charge peu après et prend le relais, en mettant à niveau le stub sur place, de sorte qu’une référence capturée plus tôt continue de fonctionner.
Cela vous donne deux catégories d’appels :

Appels de configuration : sûrs immédiatement

configure(...), events.on(...) et chaque appel hooks.register*. Mis en mémoire tampon avant le démarrage et rejoués dans l’ordre une fois le SDK chargé. Placez-les en haut de votre script.

Actions : attendez ready()

Tout ce qui est sous actions.*. Exécutez-les dans ready() ou un gestionnaire d’événement. Appelées trop tôt, elles avertissent dans la console et ne font rien, en toute sécurité : les asynchrones se résolvent quand même, donc une chaîne .then() ne cassera pas.

ready()

ready() renvoie une Promise qui se résout une fois le premier chargement du panier stabilisé. Elle se résout en cas d’échec comme de succès, donc un acheteur sur une connexion instable ne laisse jamais votre script en attente. Vérifiez que getCart() ne renvoie pas null plutôt que de supposer qu’un panier est arrivé. Appeler ready() après que le panier a déjà été chargé se résout immédiatement, il est donc sûr de l’utiliser comme barrière générale « le panier existe maintenant » n’importe où dans votre code.
Vous n’avez pas besoin de ready() dans un gestionnaire d’événement. Au moment où cart_loaded, cart_updated ou item_added se déclenche, le panier est chargé et les actions peuvent être appelées en toute sécurité.

context

window.aftersell.cart.context contient les données de l’acheteur rendues par le serveur, lisibles de manière synchrone, sans besoin de ready(). Utilisez-le pour des branchements par marché ou pays qui doivent se produire avant le chargement du panier.
storefront_access_token est le seul champ de context que le serveur ne rend pas dans cart.context. Il est ajouté à context au démarrage du panier, donc le lire en haut de votre script renvoie undefined. Attendez d’abord window.aftersell.cart.ready().
Pour afficher des paramètres de bloc différents par marché, pays ou devise, utilisez plutôt les conditions dans l’éditeur de panier. Aucun script requis. L’interface Conditions complète est disponible aujourd’hui sur Rewards.

shadowRoot

Le panier est rendu à l’intérieur d’un shadow root, donc document.querySelector ne peut rien voir à l’intérieur du tiroir. Pour atteindre un élément dans le panier, interrogez le shadow root :
Ciblez les mêmes classes publiques cart-external-* que celles utilisées par Custom CSS. Ce sont les points d’accroche pris en charge. Les jumelles cart-internal-* sont la plomberie interne du panier, interrogez donc les externes à la place.
N’utilisez le shadow root que lorsqu’aucun bloc, paramètre ou hook ne fait le travail. Un hook survit à une refonte du panier ; une requête DOM est un problème de maintenance pour votre code.
Le shadow root n’existe qu’une fois le panier démarré, donc lisez-le dans ready() ou un gestionnaire d’événement plutôt qu’en haut de votre script.

Débogage

Un script défaillant ne doit jamais faire tomber l’ajout au panier ou le tiroir, donc le SDK contient les échecs plutôt que de les laisser remonter. L’endroit où un échec apparaît dépend de ce qui a cassé :

Quand votre script lève une exception

Un script personnalisé s’arrête à la première erreur, donc chaque configure, events.on et hooks.register* sous cette ligne ne s’exécute jamais. Le panier le dit explicitement :
C’est le message à rechercher lorsqu’un gestionnaire que vous avez assurément enregistré ne se déclenche jamais : il n’a probablement jamais été atteint. Le numéro de ligne est l’instruction de niveau supérieur où l’exécution s’est arrêtée, pas la fonction interne qui a levé l’exception, et il est omis plutôt que deviné si la pile du navigateur n’est pas utilisable. Vos scripts s’exécutent également sous leurs propres noms de fichiers, ils apparaissent donc comme aftersell-cart-init.js et aftersell-cart-cart-update.js dans les DevTools. Vous pouvez les ouvrir depuis le panneau Sources et poser des points d’arrêt comme dans n’importe quel autre fichier.

Le canal de débogage

Les échecs de hooks sont délibérément tenus à l’écart de la console pour que les acheteurs ne les voient jamais. Ils vont plutôt ici :

Pour aller plus loin

Configure

Chaque option, avec un exemple pour chacune.

Events

Chaque événement, quand il se déclenche, et ce qu’il ne faut pas faire dans un gestionnaire.

Actions

Chaque action, avec un extrait pour chacune.

Hooks

Chaque hook, et comment les enregistrements se composent.

Cart object

La forme du panier et de ses lignes.

Use cases

Des solutions complètes et exécutables aux demandes courantes.