Skip to main content

​
Panoramica

Quando né le superfici native di Aftersell (post-acquisto, checkout, Upcart) né un’integrazione preconfezionata fanno al caso tuo, puoi chiamare tu stesso la Strategies API dal tuo tema Shopify e visualizzare i prodotti restituiti come preferisci. Lo schema è lo stesso in ogni caso: costruisci un payload di contesto da Liquid (in modo che gli attributi Shopify come il prodotto corrente, il contenuto del carrello e i campi del cliente vengano compilati al momento del rendering), fai una POST a /api/public/strategy/evaluate e visualizzi la risposta. Questa pagina copre due modelli di implementazione:
  • Contesto PDP - inserisci una sezione nelle pagine prodotto che chiama l’API con il prodotto attualmente visualizzato e mostra un carosello di raccomandazioni restituite.
  • Contesto carrello - visualizza un blocco di upsell all’interno di un carrello personalizzato che chiama l’API con tutte le voci attualmente nel carrello e mostra i prodotti restituiti.
Ciò che cambia tra i due è la forma del contesto prodotto: un singolo prodotto sulla PDP, un array di tutte le voci nel carrello.

​
Di cosa avrai bisogno

  1. La tua Strategy API key. In Aftersell, vai su Settings → Product Strategy e, nella scheda Security Token, copia il tuo token (questa è la tua Strategy API key).
  2. Lo Strategy ID. Apri la Strategy che vuoi eseguire nell’editor delle Strategy di Aftersell e copia il suo ID.
  3. Accesso al codice del tema. Dovrai aggiungere una sezione Liquid (PDP) o un blocco (carrello personalizzato) al tuo tema Shopify - Online Store → Themes → … → Edit code.
La tua Strategy API key risiede nel codice del tema lato client, il che la rende visibile a chiunque visualizzi il codice sorgente della pagina. Trattala come una credenziale pubblica della vetrina e ruotala da Aftersell Settings → Product Strategy se dovesse mai essere esposta in un modo non voluto.

​
Contesto PDP: snippet della sezione

Questo modello aggiunge una sezione Shopify alla tua pagina prodotto. Quando la pagina viene renderizzata, Liquid incorpora nel payload gli attributi del prodotto corrente, del carrello e del cliente, poi JavaScript effettua una POST alla Strategies API e mostra i prodotti restituiti in un carosello Splide.

​
Installazione

  1. Nel tuo pannello di amministrazione Shopify, vai su Online Store → Themes, clicca su … sul tuo tema e seleziona Edit code.
  2. Nella cartella Sections, crea un nuovo file chiamato aftersell-upsell-carousel.liquid.
  3. Incolla lo snippet qui sotto nel nuovo file e sostituisci YOUR_STRATEGY_API_KEY con l’API key di Aftersell.
  4. Salva.
  5. Apri il tuo template prodotto (di solito templates/product.json o sections/main-product.liquid) e aggiungi la sezione Aftersell Carousel nel punto in cui vuoi che appaia il carosello. Dall’editor del tema puoi anche trascinarla direttamente sulla pagina prodotto.
  6. Nelle impostazioni della sezione, incolla il tuo Strategy ID.

​
Cosa invia la sezione

Per ogni visualizzazione della PDP, il payload include:
  • products - un array con un solo elemento contenente il prodotto attualmente visualizzato (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
  • cart - subtotale, numero di articoli e numero di righe del carrello corrente dell’acquirente (omesso se il carrello è vuoto).
  • cartToken - in modo che l’API possa collegare questa valutazione alla stessa sessione.
  • customer - tag, paese, provincia, lingua, numero di ordini, spesa totale e flag accepts-marketing, ma solo se l’acquirente ha effettuato l’accesso.
  • session - codice valuta da shop.currency.
La sezione non invia i parametri UTM per impostazione predefinita. Se vuoi un targeting basato su UTM sulla PDP, acquisiscili lato client e aggiungili all’oggetto session prima della fetch.

​
Lo snippet

Un carosello di prodotti alimentato da una Strategy visualizzato su una pagina prodotto Shopify

​
Personalizzazione

Lo schema della sezione espone quattro impostazioni modificabili dal merchant: Strategy ID, Heading, CTA Button Label e Max Products to Show. Aggiungi o rimuovi impostazioni nel blocco {% schema %} per esporre più controlli nell’editor del tema. Il CSS è delimitato sotto nomi di classe .aftersell-* e include un carosello Splide a 4 elementi che passa a 2 elementi a 768px e a 1 elemento a 480px. Modificalo liberamente per adattarlo al tuo tema: nulla di tutto ciò è necessario per il funzionamento della chiamata API.

​
Contesto carrello: blocco di upsell in un carrello personalizzato

Questo modello è strutturalmente identico a quello della PDP, con una differenza chiave: l’array del contesto prodotto viene costruito dalle voci del carrello invece che dal prodotto attualmente visualizzato. La Strategy riceve quindi ogni articolo che l’acquirente ha aggiunto e restituisce raccomandazioni basate sul carrello nel suo insieme. L’implementazione vive ovunque risieda il codice del tuo carrello personalizzato: una sezione Liquid che renderizza il cart drawer, un blocco personalizzato in una vetrina headless o un template del tema come cart.liquid. La forma della chiamata API e la gestione della risposta sono identiche all’esempio della PDP: cambia solo l’array products. La struttura è questa:
Il resto del payload (cart, customer, session, cartToken) e la chiamata fetch a /api/public/strategy/evaluate rimangono invariati rispetto al modello PDP qui sopra: solo l’array products passa da [productContext] all’array derivato dal carrello.

​
Cosa succede quando la Strategy restituisce un risultato

La forma della risposta è la stessa indipendentemente dal contesto che hai inviato:
L’evaluationId è un id univoco per questa valutazione. Se lo acquisisci e lo alleghi ai prodotti che visualizzi, puoi attribuire l’ordine risultante esattamente alla raccomandazione che lo ha generato - vedi Attribuzione qui sotto. Il modo in cui visualizzi l’array products dipende interamente dal codice del tuo tema. Lo snippet PDP qui sopra li mostra come un carosello di schede con selettori di varianti e pulsanti di aggiunta al carrello; un blocco di carrello personalizzato potrebbe visualizzarli come un elenco verticale all’interno del drawer. Per lo schema completo di richiesta e risposta, consulta il riferimento API Evaluate Strategy.

​
Quando nessun prodotto viene restituito

Se la Strategy non restituisce alcun prodotto (products: []), spetta al tuo codice decidere come gestirlo. Lo snippet PDP qui sopra nasconde completamente il carosello. Un blocco di carrello personalizzato potrebbe ripiegare sull’elenco di upsell predefinito del carrello, oppure semplicemente non mostrare nulla. Per evitare una risposta vuota, configura un Catch all nella Strategy in modo che ci sia sempre un prodotto di riserva da restituire. Consulta la pagina Costruire le Strategy per scoprire come impostare un Catch all.

​
Suggerimenti per le integrazioni personalizzate

  • Costruisci il contesto in Liquid. Liquid viene eseguito al momento del rendering e ha accesso all’intero grafo degli oggetti Shopify: prodotto, carrello, cliente, negozio, richiesta. Usalo per popolare il payload lato server invece di ricorrere a chiamate lato client.
  • Tieni l’API key fuori dai repository pubblici. Finirà nel codice del tuo tema, che viene consegnato al browser - e questo va bene. Ma non incollare lo stesso tema in un repository pubblico né condividere il bundle esternamente.
  • Usa un Catch all. Le esperienze in vetrina sembrano rotte quando uno slot scompare. Un Catch all con un piccolo set di prodotti sicuri di default mantiene l’interfaccia coerente.
  • Metti in cache dove ha senso. La Strategies API fa un leggero caching lato server (meta.servedFromCache), ma per le PDP ad alto traffico potresti anche voler applicare debounce o memoizzazione alle chiamate lato client (es. non richiamare quando lo stesso prodotto viene renderizzato due volte in una sessione).

​
Attribuzione

Quando un acquirente clicca sul pulsante di aggiunta al carrello nello snippet, la chiamata /cart/add.js allega delle line item properties all’articolo del carrello:
Queste proprietà viaggiano con la voce del carrello fino all’ordine Shopify, dove compaiono nel record della voce. Puoi usarle a valle per attribuire i ricavi, filtrare gli ordini o alimentare strumenti di analytics che leggono le line item properties. Le chiavi e i valori sono convenzioni, non requisiti: la chiamata API funziona allo stesso modo indipendentemente da cosa inserisci qui. Modificale per adattarle al tuo modello di attribuzione. Per esempio:
Le chiavi di proprietà che iniziano con un trattino basso (_) sono nascoste nell’interfaccia del carrello e del checkout ma restano comunque allegate all’ordine. Usa il prefisso con trattino basso per i metadati di sola attribuzione che non vuoi far vedere agli acquirenti.
Applica lo stesso schema nell’implementazione con contesto carrello: qualsiasi chiamata di aggiunta al carrello effettuata da un blocco di upsell personalizzato può portare con sé tutte le proprietà di cui hai bisogno.

​
Attribuire alla valutazione

Per collegare un ordine alla valutazione esatta che ha raccomandato il prodotto - anziché solo a “proviene da una Strategy” - acquisisci l’evaluationId dalla risposta e allegalo alla voce del carrello sotto la proprietà __as_offer_id. AfterSell legge questa chiave, quindi gli ordini contrassegnati con essa vengono attribuiti alla valutazione specifica nella reportistica. Nell’handler evaluate(), conserva l’id dalla risposta:
Poi includilo nelle proprietà di aggiunta al carrello:
Mantieni il doppio trattino basso su __as_offer_id: è la chiave che AfterSell cerca, e il prefisso con trattino basso la tiene nascosta agli acquirenti. Se evaluationId è assente (per esempio, se non è stato restituito alcun prodotto), ometti la proprietà anziché inviare un valore vuoto.