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

# Script personalizzati

> Esegui JavaScript personalizzato nell'Aftersell Cart con gli slot per script Initialization e On cart update.

Gli script personalizzati ti permettono di eseguire il tuo JavaScript sul carrello usando il [Cart SDK](/it/aftersell/cart/sdk-overview). Aggiungili nel cart editor sotto **Cart settings → Custom script**, dove un menu a tendina passa tra due slot: **Initialization** e **On cart update**.

Scrivi JavaScript puro in questi editor, senza tag `<script>`. **On cart update** ha un'azione **Reset to default** che ripristina il suo template iniziale; **Initialization** no, quindi conserva una copia del tuo codice prima di cancellarlo.

<Note>
  Molto di ciò che i merchant scrivevano come script è ora un'impostazione integrata. Controlla prima [Prima di scrivere uno script](/it/aftersell/cart/sdk-use-cases#before-you-write-a-script): un'impostazione continua a funzionare attraverso i redesign del carrello, mentre il tuo script potrebbe no.
</Note>

<div id="which-slot-to-use">
  ## Quale slot usare
</div>

|                 | Initialization                                                                                                                                                                             | On cart update                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **Esecuzione**  | Una volta, quando il carrello si carica.                                                                                                                                                   | A ogni modifica del carrello dopo il primo caricamento.                  |
| **Cosa scrivi** | L'intero script.                                                                                                                                                                           | Solo il corpo dell'handler. Il wrapper `cart_updated` è bloccato.        |
| **Usalo per**   | Registrare comportamenti una sola volta: [`configure`](/it/aftersell/cart/sdk-configure), [`events.on`](/it/aftersell/cart/sdk-events), [`hooks.register*`](/it/aftersell/cart/sdk-hooks). | Regole che devono essere rivalutate sul contenuto corrente del carrello. |
| **Esempio**     | Nascondere le righe degli omaggi con un line transform.                                                                                                                                    | Mantenere un omaggio sincronizzato con una soglia di spesa.              |

<div id="initialization">
  ## Initialization
</div>

Lo script **Initialization** viene eseguito **una volta quando il carrello si carica**. È il tuo punto di ingresso per configurare tutto: impostare il comportamento del carrello, iscriverti agli eventi e registrare gli hook. L'[SDK](/it/aftersell/cart/sdk-overview) è disponibile come `window.aftersell.cart`.

Le chiamate di setup che fai qui ([`configure(...)`](/it/aftersell/cart/sdk-configure), [`events.on(...)`](/it/aftersell/cart/sdk-events), [`hooks.*`](/it/aftersell/cart/sdk-hooks)) possono essere chiamate in sicurezza all'inizio dello script anche prima che il carrello sia completamente avviato; vengono messe in buffer e applicate una volta pronto. Le azioni che leggono o modificano il carrello (come [`addItem`](/it/aftersell/cart/sdk-actions#additemvariantid-quantity) o [`getCart`](/it/aftersell/cart/sdk-actions#getcart)) dovrebbero essere eseguite dentro [`ready()`](/it/aftersell/cart/sdk-overview#ready) o un handler di eventi.

Lo slot parte con tre esempi **commentati** — aprire il drawer a ogni aggiunta, reagire a `cart_loaded` e nascondere le righe degli omaggi — quindi uno script Initialization non modificato non fa nulla. Rimuovi il commento da uno per provarlo, oppure sostituiscili.

La forma naturale per questo slot è una **registrazione una tantum senza eventi coinvolti**: registra il comportamento una volta e lascia che il carrello lo applichi da quel momento in poi. Nascondere le righe degli omaggi dal drawer, senza cambiare il totale, è l'esempio fornito di questo:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) line.setHidden(true);
});
```

[`registerLineTransform`](/it/aftersell/cart/sdk-hooks#registerlinetransform) viene eseguito per ogni riga durante il render, e `setHidden` riguarda solo la visualizzazione, quindi la riga resta nel carrello e conta comunque nel totale, semplicemente non appare nel drawer. Consulta [Nascondere e rietichettare le righe del carrello](/it/aftersell/cart/sdk-use-case-hide-lines) per altre possibilità di un transform.

Le azioni che leggono il carrello vanno dentro `ready()`:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log('Cart loaded with', state.itemCount, 'items');
});
```

Accedere al DOM del carrello richiede la stessa attesa, e richiede [`shadowRoot`](/it/aftersell/cart/sdk-overview#shadowroot): il carrello viene renderizzato dentro uno shadow root, quindi `document.querySelector` non può vedere nulla nel drawer.

<Tip>
  Devi ramificare per mercato, paese o valuta **prima** che il carrello si carichi? Leggi invece [`context`](/it/aftersell/cart/sdk-overview#context). È disponibile in modo sincrono, senza bisogno di `ready()`, così puoi evitare del tutto di registrare handler per gli acquirenti a cui una regola non si applica.
</Tip>

<div id="on-cart-update">
  ## On cart update
</div>

Lo script **On cart update** viene eseguito ogni volta che il carrello cambia. È un wrapper bloccato attorno a un'iscrizione a `cart_updated`, quindi modifichi solo il corpo, e il tuo codice riceve il `cart` aggiornato.

Questo slot è per le regole che devono essere **rivalutate a ogni modifica del carrello**. Una soglia per l'omaggio è il caso classico (spendi \$75, ricevi una tote gratis) perché la risposta dipende dal contenuto corrente e nient'altro può dirti quando cambia:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (cart) => {
  const GIFT_VARIANT_ID = 1234567890;
  const THRESHOLD = 7500;   // $75.00, in cents

  let giftLine = null;
  let subtotal = 0;
  (cart.items ?? []).forEach((line) => {
    if (line.variantId === GIFT_VARIANT_ID) giftLine = line;
    else subtotal += line.finalLinePrice;   // the gift itself never counts toward the threshold
  });

  const shouldHaveGift = subtotal >= THRESHOLD;
  const hasGift = Boolean(giftLine);

  // Bail when the cart already matches. This is the part that matters: adding or
  // removing an item fires cart_updated again, so without this check the handler
  // re-enters itself forever.
  if (shouldHaveGift === hasGift) return;

  if (shouldHaveGift) window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  else window.aftersell.cart.actions.removeItem(giftLine.key);
});
```

<div id="keeping-the-cart-in-a-desired-state">
  ### Mantenere il carrello in uno stato desiderato
</div>

La riga `if (shouldHaveGift === hasGift) return;` è ciò che rende tutto questo sicuro, e si generalizza a ogni script che mantiene il carrello in uno stato desiderato. Questo slot sia reagisce alle modifiche del carrello sia le provoca, quindi ogni `addItem` o `removeItem` vi rientra. Descrivi lo stato che vuoi, confrontalo con lo stato che hai e termina subito quando già coincidono, così l'handler converge dopo un solo passaggio invece di andare in loop. Consulta [le due regole](/it/aftersell/cart/sdk-events#the-two-rules) per la versione senza protezione da evitare e per il motivo per cui il payload è in sola lettura.

Su un negozio più lento vale anche la pena mantenere un flag di operazione in corso a livello di modulo, così due modifiche rapide non possono entrambe avviare un'aggiunta prima che la prima sia completata.

<Note>
  `cart_updated` scatta solo per le modifiche **dopo** il primo caricamento ([tempistiche degli eventi](/it/aftersell/cart/sdk-events#cart_updated)), quindi uno script in questo slot non riconcilierà un carrello che è già idoneo al caricamento della pagina. Per una versione che gestisce entrambi i casi, iscriviti a `cart_loaded` e `cart_updated` con la stessa funzione dallo slot **Initialization**. Consulta [Aggiungere automaticamente un omaggio a una soglia](/it/aftersell/cart/sdk-use-case-free-gift).
</Note>

<div id="when-a-script-breaks">
  ## Quando uno script si rompe
</div>

Ogni slot viene eseguito nella propria sandbox, quindi uno script **Initialization** rotto non può impedire l'esecuzione di **On cart update**, e nessuno dei due può rompere il carrello stesso.

All'interno di uno slot, però, l'esecuzione **si ferma al primo errore**. Tutto ciò che sta sotto quella riga viene saltato, il che significa che qualsiasi `configure`, `events.on` o `hooks.register*` più in basso non viene mai registrato. È la spiegazione più comune di "il mio handler non scatta mai" quando il codice sembra corretto.

Il carrello indica la riga che fallisce nella console del browser, e ogni slot viene eseguito con il proprio nome di file (`aftersell-cart-init.js` e `aftersell-cart-cart-update.js`), così puoi aprirne uno dal pannello Sources dei DevTools e impostare breakpoint. Consulta [Debugging](/it/aftersell/cart/sdk-overview#debugging) per i messaggi esatti e per il canale di debug che cattura gli errori degli hook tenuti fuori dalla console.

Poiché `cart_loaded` [viene riproposto agli iscritti in ritardo](/it/aftersell/cart/sdk-events#cart_loaded), l'ordine di registrazione non conta mai. La struttura più sicura è registrare tutto prima e fare il lavoro rischioso dentro gli handler, dove un errore resta isolato a quell'handler.

<div id="where-to-go-next">
  ## Dove andare dopo
</div>

* **[Cart SDK](/it/aftersell/cart/sdk-overview)**: gli script personalizzati sono il modo in cui esegui il codice dell'SDK. Consulta i riferimenti di [configure](/it/aftersell/cart/sdk-configure), [eventi](/it/aftersell/cart/sdk-events), [azioni](/it/aftersell/cart/sdk-actions) e [hook](/it/aftersell/cart/sdk-hooks) per l'intera superficie, l'[oggetto carrello](/it/aftersell/cart/sdk-cart-object) per la forma di ciò che gli handler ricevono, e i [casi d'uso](/it/aftersell/cart/sdk-use-cases) per snippet pronti all'uso.
* **[Blocchi Custom code](/it/aftersell/cart/custom-code-blocks)**: per aggiungere markup al carrello. Nota che la modalità HTML del blocco Custom code **non** esegue JavaScript; usa gli script personalizzati (o la modalità React del blocco) per la logica.