> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aperçu

> Comment fonctionne le SDK du panier Aftersell : le point d'entrée global, les quatre parties de l'API, quand il se charge et comment exécuter du code dessus en toute sécurité.

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](/fr/aftersell/cart/custom-scripts), ou via le mode React d'un [bloc Custom code](/fr/aftersell/cart/custom-code-blocks) pour un bloc qui affiche sa propre interface.

<Note>
  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](/fr/aftersell/cart/blocks-overview), des [conditions par marché/pays/devise](/fr/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) ou un [paramètre de panier](/fr/aftersell/cart/cart-settings) 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.
</Note>

<div id="the-global-entry-point">
  ## Le point d'entrée global
</div>

Tout part d'un seul global :

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart
```

<Note>
  **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`.
</Note>

Quatre parties font le travail :

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/fr/aftersell/cart/sdk-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.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/fr/aftersell/cart/sdk-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é.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/fr/aftersell/cart/sdk-actions">
    Lisez et modifiez le panier : ouvrez-le, ajoutez un article, mettez à jour une quantité, lisez l'état actuel.
  </Card>

  <Card title="Hooks" icon="plug" href="/fr/aftersell/cart/sdk-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.
  </Card>
</Columns>

<Note>
  Si un de vos scripts a cessé de se déclencher à l'ajout au panier, commencez par [Interception de l'ajout au panier](/fr/aftersell/cart/add-to-cart-interception). Elle explique pourquoi Aftersell prend en charge l'ajout, et toutes les façons de désinscrire un formulaire.
</Note>

Plus trois membres plus modestes :

| Membre       | À quoi il sert                                                                  |
| ------------ | ------------------------------------------------------------------------------- |
| `ready()`    | Une Promise qui se résout une fois le panier chargé pour la première fois.      |
| `context`    | Contexte de l'acheteur rendu côté serveur, lisible de manière synchrone.        |
| `shadowRoot` | Le shadow root du panier, pour interroger les éléments à l'intérieur du tiroir. |

<div id="events-actions-or-hooks">
  ## Événements, actions ou hooks ?
</div>

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 :

| Vous voulez…                                      | Utilisez      | Exemple                                                        |
| ------------------------------------------------- | ------------- | -------------------------------------------------------------- |
| Exécuter du code *quand quelque chose se produit* | **Événement** | Envoyer un événement d'analyse quand un article est ajouté.    |
| *Changer ce qui est dans* le panier               | **Action**    | Ajouter un cadeau gratuit une fois le total au-dessus de \$50. |
| Changer *le fonctionnement ou le rendu du panier* | **Hook**      | Masquer les lignes de cadeau gratuit du tiroir.                |

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.

<div id="how-and-when-it-loads">
  ## Comment et quand il se charge
</div>

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 :

<Columns cols={2}>
  <Card title="Appels de configuration : sûrs immédiatement" icon="circle-check">
    `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.
  </Card>

  <Card title="Actions : attendez ready()" icon="clock">
    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.
  </Card>
</Columns>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// 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');
});
```

<div id="ready">
  ### ready()
</div>

`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.

<Tip>
  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é.
</Tip>

<div id="context">
  ## context
</div>

`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.

| Champ                     | Description                                                                               | Disponible avant le démarrage          |
| ------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- |
| `shopify_market`          | Le marché Shopify de l'acheteur.                                                          | Oui                                    |
| `customer_country`        | Code pays à deux lettres.                                                                 | Oui                                    |
| `customer_currency`       | Code de la devise active.                                                                 | Oui                                    |
| `money_format`            | Le format monétaire Shopify de la boutique.                                               | Oui                                    |
| `backend_url`             | Hôte backend direct, utilisé en secours quand le proxy d'application n'est pas configuré. | Oui                                    |
| `storefront_access_token` | Token pour les appels à l'API Storefront.                                                 | **Non**. Ajouté au démarrage du panier |

<Warning>
  `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()`.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}
```

<Note>
  Pour afficher des paramètres de bloc différents par marché, pays ou devise, utilisez plutôt les [conditions dans l'éditeur de panier](/fr/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency). Aucun script requis. L'interface Conditions complète est disponible aujourd'hui sur [Rewards](/fr/aftersell/cart/rewards-block#per-market-rewards).
</Note>

<div id="shadowroot">
  ## shadowRoot
</div>

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 :

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');
```

Ciblez les mêmes **classes publiques `cart-external-*`** que celles utilisées par [Custom CSS](/fr/aftersell/cart/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.

<Warning>
  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.
</Warning>

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.

<div id="debugging">
  ## Débogage
</div>

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é :

| Ce qui a échoué                                                                           | Où cela apparaît                                                   |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Votre script a levé une exception au niveau supérieur                                     | `console.error`, nommant la ligne et ce qui n'a jamais été exécuté |
| Un gestionnaire d'[événement](/fr/aftersell/cart/sdk-events) a levé une exception         | `console.error` ; les autres gestionnaires s'exécutent quand même  |
| Un [hook](/fr/aftersell/cart/sdk-hooks) a levé une exception                              | Silencieux. Va dans le canal de débogage ci-dessous                |
| Une [action](/fr/aftersell/cart/sdk-actions) s'est exécutée avant le chargement du panier | `console.warn` ; l'appel ne fait rien                              |

<div id="when-your-script-throws">
  ### Quand votre script lève une exception
</div>

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 :

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

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.

<div id="the-debug-channel">
  ### Le canal de débogage
</div>

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 :

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// 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));
```

<div id="where-to-go-next">
  ## Pour aller plus loin
</div>

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/fr/aftersell/cart/sdk-configure">
    Chaque option, avec un exemple pour chacune.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/fr/aftersell/cart/sdk-events">
    Chaque événement, quand il se déclenche, et ce qu'il ne faut pas faire dans un gestionnaire.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/fr/aftersell/cart/sdk-actions">
    Chaque action, avec un extrait pour chacune.
  </Card>

  <Card title="Hooks" icon="plug" href="/fr/aftersell/cart/sdk-hooks">
    Chaque hook, et comment les enregistrements se composent.
  </Card>

  <Card title="Cart object" icon="table-list" href="/fr/aftersell/cart/sdk-cart-object">
    La forme du panier et de ses lignes.
  </Card>

  <Card title="Use cases" icon="book-open" href="/fr/aftersell/cart/sdk-use-cases">
    Des solutions complètes et exécutables aux demandes courantes.
  </Card>
</Columns>