Panoramica

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, oppure tramite la modalità React di un blocco Custom code per un blocco che renderizza la propria UI.

Molto di ciò che i merchant chiedono all’SDK è già un’impostazione. Prima di scrivere uno script, verifica se un blocco del carrello, le condizioni per mercato/paese/valuta o un’impostazione del carrello lo fanno già. Quelli continuano a funzionare attraverso i redesign del carrello, mentre il tuo script potrebbe non farlo.

Il punto di ingresso globale

Tutto dipende da un unico global:

window.aftersell.cart

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.

Quattro parti fanno il lavoro:

Configure

Imposta come si comporta il carrello: quando si apre il drawer, come viene formattato il denaro, se Aftersell intercetta l’aggiunta al carrello.

Events

Reagisci a ciò che succede: il carrello si è caricato, è stato aggiunto un articolo, il drawer si è aperto, è stato cliccato il checkout.

Actions

Leggi e modifica il carrello: aprilo, aggiungi un articolo, aggiorna una quantità, leggi lo stato attuale.

Hooks

Cambia come funziona il carrello stesso: nascondi o rietichetta le righe, riordinale, allega dati extra, controlla l’aggiunta al carrello.

Se uno script tuo ha smesso di attivarsi sull’add-to-cart, inizia da Intercettazione dell’add-to-cart. Spiega perché Aftersell prende il controllo dell’aggiunta e ogni modo per escludere un form.

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.

Eventi, azioni o hook?

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.

Come e quando si carica

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

Un piccolo stub crea window.aftersell.cart immediatamente, quindi è sempre presente.
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:

Chiamate di set-up: sicure immediatamente

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.

Azioni: aspetta ready()

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.

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

ready()

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.

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.

context

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

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

if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}

Per mostrare impostazioni di blocco diverse per mercato, paese o valuta, usa invece le condizioni nel cart editor. Nessuno script richiesto. La UI completa delle Condizioni è disponibile oggi su Rewards.

shadowRoot

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:

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. Quelli sono gli handle supportati. Le gemelle cart-internal-* sono la struttura interna del carrello, quindi interroga invece quelle esterne.

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.

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.

Debugging

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 ha lanciato un errore	`console.error`; gli altri gestori vengono comunque eseguiti
Un hook ha lanciato un errore	Silenzioso. Va nel canale di debug qui sotto
Un’azione è stata eseguita prima che il carrello si caricasse	`console.warn`; la chiamata non fa nulla

Quando il tuo script lancia un errore

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.

Il canale di debug

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

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

Dove andare adesso

Configure

Ogni opzione, con un esempio ciascuna.

Events

Ogni evento, quando si attiva e cosa non fare in un gestore.

Actions

Ogni azione, con uno snippet ciascuna.

Hooks

Ogni hook, e come si compongono le registrazioni.

Cart object

La struttura del carrello e delle sue righe.

Use cases

Soluzioni complete ed eseguibili alle richieste comuni.

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

Il punto di ingresso globale

Configure

Events

Actions

Hooks

Eventi, azioni o hook?

Come e quando si carica

Chiamate di set-up: sicure immediatamente

Azioni: aspetta ready()

ready()

context

shadowRoot

Debugging

Quando il tuo script lancia un errore

Il canale di debug

Dove andare adesso

Configure

Events

Actions

Hooks

Cart object

Use cases

​Il punto di ingresso globale

Configure

Events

Actions

Hooks

​Eventi, azioni o hook?

​Come e quando si carica

Chiamate di set-up: sicure immediatamente

Azioni: aspetta ready()

​ready()

​context

​shadowRoot

​Debugging

​Quando il tuo script lancia un errore

​Il canale di debug

​Dove andare adesso

Configure

Events

Actions

Hooks

Cart object

Use cases

Il punto di ingresso globale

Eventi, azioni o hook?

Come e quando si carica

ready()

context

shadowRoot

Debugging

Quando il tuo script lancia un errore

Il canale di debug

Dove andare adesso