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

# Panoramica

> Come funziona il Cart SDK di Aftersell: il punto di ingresso globale, le quattro parti dell'API, quando si carica e come eseguire codice su di esso in sicurezza.

Il **Cart SDK** è un'API JavaScript per l'Aftersell Cart sul tuo storefront. Ti permette di cambiare il comportamento del carrello, reagire a ciò che fanno gli acquirenti e leggere o modificare il contenuto del carrello da codice.

Esegui il codice dell'SDK tramite gli [Script personalizzati](/it/aftersell/cart/custom-scripts), oppure tramite la modalità React di un [blocco Custom code](/it/aftersell/cart/custom-code-blocks) per un blocco che renderizza la propria UI.

<Note>
  Molto di ciò che i merchant chiedono all'SDK è già un'impostazione. Prima di scrivere uno script, verifica se un [blocco del carrello](/it/aftersell/cart/blocks-overview), le [condizioni per mercato/paese/valuta](/it/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) o un'[impostazione del carrello](/it/aftersell/cart/cart-settings) lo fanno già. Quelli continuano a funzionare attraverso i redesign del carrello, mentre il tuo script potrebbe non farlo.
</Note>

<div id="the-global-entry-point">
  ## Il punto di ingresso globale
</div>

Tutto dipende da un unico global:

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

<Note>
  **Ogni snippet in questa documentazione scrive `window.aftersell.cart` per esteso**, quindi ognuno di essi funziona da solo quando lo incolli. Creare un alias una volta (`const cart = window.aftersell.cart;`) e usare `cart` da lì in poi è altrettanto valido, e sicuro anche prima che il carrello si carichi. Ricorda solo di includere quella riga se accorci uno snippet, perché un `cart` da solo lancia `cart is not defined`.
</Note>

Quattro parti fanno il lavoro:

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/it/aftersell/cart/sdk-configure">
    Imposta come si comporta il carrello: quando si apre il drawer, come viene formattato il denaro, se Aftersell intercetta l'aggiunta al carrello.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/it/aftersell/cart/sdk-events">
    Reagisci a ciò che succede: il carrello si è caricato, è stato aggiunto un articolo, il drawer si è aperto, è stato cliccato il checkout.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/it/aftersell/cart/sdk-actions">
    Leggi e modifica il carrello: aprilo, aggiungi un articolo, aggiorna una quantità, leggi lo stato attuale.
  </Card>

  <Card title="Hooks" icon="plug" href="/it/aftersell/cart/sdk-hooks">
    Cambia come funziona il carrello stesso: nascondi o rietichetta le righe, riordinale, allega dati extra, controlla l'aggiunta al carrello.
  </Card>
</Columns>

<Note>
  Se uno script tuo ha smesso di attivarsi sull'add-to-cart, inizia da [Intercettazione dell'add-to-cart](/it/aftersell/cart/add-to-cart-interception). Spiega perché Aftersell prende il controllo dell'aggiunta e ogni modo per escludere un form.
</Note>

Più tre membri minori:

| Membro       | A cosa serve                                                                           |
| ------------ | -------------------------------------------------------------------------------------- |
| `ready()`    | Una Promise che si risolve una volta che il carrello si è caricato per la prima volta. |
| `context`    | Contesto dell'acquirente renderizzato dal server, leggibile in modo sincrono.          |
| `shadowRoot` | Lo shadow root del carrello, per interrogare gli elementi dentro il drawer.            |

<div id="events-actions-or-hooks">
  ## Eventi, azioni o hook?
</div>

I tre sono facili da confondere, e scegliere quello sbagliato è il motivo più comune per cui uno script non fa ciò che il suo autore si aspettava:

| Vuoi…                                             | Usa        | Esempio                                                           |
| ------------------------------------------------- | ---------- | ----------------------------------------------------------------- |
| Eseguire codice *quando succede qualcosa*         | **Evento** | Inviare un evento di analytics quando viene aggiunto un articolo. |
| *Cambiare il contenuto* del carrello              | **Azione** | Aggiungere un omaggio quando il totale supera \$50.               |
| Cambiare *come il carrello funziona o renderizza* | **Hook**   | Nascondere le righe degli omaggi dal drawer.                      |

La distinzione che conta di più: un'**azione modifica il carrello reale dell'acquirente** (e il suo totale), mentre un **hook cambia solo ciò che viene renderizzato**. Nascondere una riga con un hook la lascia nel carrello e nel totale; rimuoverla con un'azione la toglie per davvero.

<div id="how-and-when-it-loads">
  ## Come e quando si carica
</div>

Il carrello si carica in due fasi, e l'SDK è costruito in modo che tu non debba pensare all'ordinamento:

1. Un piccolo **stub** crea `window.aftersell.cart` immediatamente, quindi è sempre presente.
2. L'SDK completo si carica poco dopo e prende il controllo, aggiornando lo stub sul posto, così un riferimento catturato in precedenza continua a funzionare.

Questo ti dà due categorie di chiamate:

<Columns cols={2}>
  <Card title="Chiamate di set-up: sicure immediatamente" icon="circle-check">
    `configure(...)`, `events.on(...)` e ogni chiamata `hooks.register*`. Vengono bufferizzate prima del boot e riprodotte in ordine quando l'SDK si carica. Mettile all'inizio del tuo script.
  </Card>

  <Card title="Azioni: aspetta ready()" icon="clock">
    Tutto ciò che sta sotto `actions.*`. Eseguile dentro `ready()` o un gestore di eventi. Chiamate troppo presto avvisano nella console e non fanno nulla, in sicurezza: quelle asincrone si risolvono comunque, quindi una catena `.then()` non si rompe.
  </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()` restituisce una Promise che si risolve quando il primo caricamento del carrello **si conclude**. Si risolve sia in caso di fallimento che di successo, quindi un acquirente con una connessione instabile non lascia mai il tuo script in sospeso. Verifica se `getCart()` è `null` invece di dare per scontato che sia arrivato un carrello.

Chiamare `ready()` dopo che il carrello si è già caricato si risolve immediatamente, quindi è sicuro usarlo come porta generale di "il carrello ora esiste" ovunque nel tuo codice.

<Tip>
  Non ti serve `ready()` dentro un gestore di eventi. Quando si attiva `cart_loaded`, `cart_updated` o `item_added`, il carrello è caricato e le azioni si possono chiamare in sicurezza.
</Tip>

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

`window.aftersell.cart.context` contiene dati dell'acquirente renderizzati dal server, leggibili in modo sincrono, senza bisogno di `ready()`. Usalo per ramificazioni per mercato o paese che devono avvenire prima che il carrello si carichi.

| Campo                     | Descrizione                                                                     | Disponibile prima del boot                    |
| ------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------- |
| `shopify_market`          | Il mercato Shopify dell'acquirente.                                             | Sì                                            |
| `customer_country`        | Codice paese a due lettere.                                                     | Sì                                            |
| `customer_currency`       | Codice della valuta attiva.                                                     | Sì                                            |
| `money_format`            | Il formato monetario Shopify del negozio.                                       | Sì                                            |
| `backend_url`             | Host backend diretto, usato come fallback quando l'app proxy non è configurato. | Sì                                            |
| `storefront_access_token` | Token per le chiamate alla Storefront API.                                      | **No** — aggiunto quando il carrello si avvia |

<Warning>
  `storefront_access_token` è l'unico campo di `context` che il server non renderizza in `cart.context`. Viene aggiunto a `context` quando il carrello si avvia, quindi leggerlo all'inizio del tuo script restituisce `undefined`. Prima fai await di `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>
  Per mostrare impostazioni di blocco diverse per mercato, paese o valuta, usa invece le [condizioni nel cart editor](/it/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency). Nessuno script richiesto. La UI completa delle Condizioni è disponibile oggi su [Rewards](/it/aftersell/cart/rewards-block#per-market-rewards).
</Note>

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

Il carrello renderizza dentro uno shadow root, quindi `document.querySelector` **non può vedere nulla dentro il drawer**. Per raggiungere un elemento nel carrello, interroga lo 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');
```

Punta alle stesse **classi pubbliche `cart-external-*`** che usa il [CSS personalizzato](/it/aftersell/cart/custom-css). Quelli sono gli handle supportati. Le gemelle `cart-internal-*` sono la struttura interna del carrello, quindi interroga invece quelle esterne.

<Warning>
  Ricorri allo shadow root solo quando nessun blocco, impostazione o hook fa il lavoro. Un hook sopravvive a un redesign del carrello; una query sul DOM è un problema di manutenzione del tuo codice.
</Warning>

Lo shadow root è presente solo dopo che il carrello si è avviato, quindi leggilo dentro `ready()` o un gestore di eventi invece che all'inizio del tuo script.

<div id="debugging">
  ## Debugging
</div>

Uno script rotto non deve mai mettere fuori uso l'aggiunta al carrello o il drawer, quindi l'SDK contiene i fallimenti invece di lasciarli propagare. Dove emerge un fallimento dipende da cosa si è rotto:

| Cosa è fallito                                                                                  | Dove appare                                                                   |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Il tuo script ha lanciato un errore al livello superiore                                        | `console.error`, con il nome della riga e di ciò che non è mai stato eseguito |
| Un gestore di un [evento](/it/aftersell/cart/sdk-events) ha lanciato un errore                  | `console.error`; gli altri gestori vengono comunque eseguiti                  |
| Un [hook](/it/aftersell/cart/sdk-hooks) ha lanciato un errore                                   | Silenzioso. Va nel canale di debug qui sotto                                  |
| Un'[azione](/it/aftersell/cart/sdk-actions) è stata eseguita prima che il carrello si caricasse | `console.warn`; la chiamata non fa nulla                                      |

<div id="when-your-script-throws">
  ### Quando il tuo script lancia un errore
</div>

Uno script personalizzato **si ferma al primo errore**, quindi ogni `configure`, `events.on` e `hooks.register*` sotto quella riga non viene mai eseguito. Il carrello lo dice esplicitamente:

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

Questo è il messaggio da cercare quando un gestore che hai sicuramente registrato non si attiva mai: probabilmente non è mai stato raggiunto. Il numero di riga è l'istruzione di livello superiore dove l'esecuzione si è fermata, non la funzione interna che ha lanciato l'errore, e viene omesso invece che indovinato se lo stack del browser non è utilizzabile.

I tuoi script vengono eseguiti anche con i propri nomi di file, quindi appaiono come `aftersell-cart-init.js` e `aftersell-cart-cart-update.js` in DevTools. Puoi aprirli dal pannello Sources e impostare breakpoint come per qualsiasi altro file.

<div id="the-debug-channel">
  ### Il canale di debug
</div>

I fallimenti degli hook sono tenuti deliberatamente fuori dalla console così gli acquirenti non li vedono mai. Vanno invece qui:

```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">
  ## Dove andare adesso
</div>

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/it/aftersell/cart/sdk-configure">
    Ogni opzione, con un esempio ciascuna.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/it/aftersell/cart/sdk-events">
    Ogni evento, quando si attiva e cosa non fare in un gestore.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/it/aftersell/cart/sdk-actions">
    Ogni azione, con uno snippet ciascuna.
  </Card>

  <Card title="Hooks" icon="plug" href="/it/aftersell/cart/sdk-hooks">
    Ogni hook, e come si compongono le registrazioni.
  </Card>

  <Card title="Cart object" icon="table-list" href="/it/aftersell/cart/sdk-cart-object">
    La struttura del carrello e delle sue righe.
  </Card>

  <Card title="Use cases" icon="book-open" href="/it/aftersell/cart/sdk-use-cases">
    Soluzioni complete ed eseguibili alle richieste comuni.
  </Card>
</Columns>