Script personalizzati

Gli script personalizzati ti permettono di eseguire il tuo JavaScript sul carrello usando il Cart SDK. 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.

Molto di ciò che i merchant scrivevano come script è ora un’impostazione integrata. Controlla prima Prima di scrivere uno script: un’impostazione continua a funzionare attraverso i redesign del carrello, mentre il tuo script potrebbe no.

Quale slot usare

	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`, `events.on`, `hooks.register*`.	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.

Initialization

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 è disponibile come window.aftersell.cart. Le chiamate di setup che fai qui (configure(...), events.on(...), 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 o getCart) dovrebbero essere eseguite dentro 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:

window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) line.setHidden(true);
});

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 per altre possibilità di un transform. Le azioni che leggono il carrello vanno dentro ready():

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: il carrello viene renderizzato dentro uno shadow root, quindi document.querySelector non può vedere nulla nel drawer.

Devi ramificare per mercato, paese o valuta prima che il carrello si carichi? Leggi invece 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.

On cart update

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:

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);
});

Mantenere il carrello in uno stato desiderato

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

cart_updated scatta solo per le modifiche dopo il primo caricamento (tempistiche degli eventi), 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.

Quando uno script si rompe

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

Dove andare dopo

Cart SDK: gli script personalizzati sono il modo in cui esegui il codice dell’SDK. Consulta i riferimenti di configure, eventi, azioni e hook per l’intera superficie, l’oggetto carrello per la forma di ciò che gli handler ricevono, e i casi d’uso per snippet pronti all’uso.
Blocchi Custom code: 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.

Per iniziare

Pagina iniziale

Best practice

Upsell post-acquisto

Carrello

Upsell al checkout (Shopify Plus)

Pagina di ringraziamento

Upsell nella pagina prodotto

Rokt Thanks

Strategie

Analisi e monitoraggio

Integrazioni

Aftersell MCP

Fatturazione e account

Risoluzione dei problemi

Quale slot usare

Initialization

On cart update

Mantenere il carrello in uno stato desiderato

Quando uno script si rompe

Dove andare dopo

​Quale slot usare

​Initialization

​On cart update

​Mantenere il carrello in uno stato desiderato

​Quando uno script si rompe

​Dove andare dopo

Quale slot usare

Initialization

On cart update

Mantenere il carrello in uno stato desiderato

Quando uno script si rompe

Dove andare dopo