Combora — Manuale utente

1Che cos'è Combora

Combora crea bundle e offerte automatiche nel Suo negozio Shopify: raggruppa i prodotti, applica lo sconto corretto nel carrello e al checkout, e mostra l'offerta nel Suo tema tramite blocchi già pronti. Lei configura l'offerta nell'admin, e lo sconto viene calcolato da una Shopify Function all'interno del checkout stesso — il prezzo addebitato è quello che calcola la piattaforma stessa, non uno script nel browser.

Esistono 8 tipi di bundle. Questa tabella La aiuta a scegliere:

Se è indeciso tra i tipi, l'app stessa offre una guida: sotto Crea bundle, il link "Non è sicuro di quale scegliere?" apre una procedura guidata, e ogni tipo ha un pannello "Guarda come funziona" con esempi.

2Primi passi

2.1 Cosa crea l'app all'installazione

Installare Combora non cambia nulla di visibile nel Suo negozio. In background l'app prepara le strutture dati dove pubblicherà i Suoi bundle (metaobject e metafield con il prefisso combora — il dettaglio tecnico è nell'appendice per sviluppatori) più un unico sconto automatico chiamato "Combora" sotto Sconti, che è quello che applica ogni prezzo. Non lo elimini né lo modifichi manualmente: l'app lo mantiene da sola.

2.2 Attivare il motore dei regali (app embed)

Se intende usare Regalo con l'acquisto (o combo con un regalo), attivi l'app embed Combora Gift: Negozio online → Personalizza → Impostazioni tema → App embed → Combora Gift. È il componente che aggiunge e rimuove il regalo dal carrello automaticamente. Senza di esso lo sconto sul regalo sarebbe comunque corretto, ma il prodotto regalo non si aggiungerebbe da solo.

2.3 Aggiungere i blocchi al Suo tema

Ogni tipo di bundle viene mostrato sul negozio online tramite un blocco del tema. Li aggiunge una sola volta sotto Negozio online → Personalizza, nel template corrispondente:

Non deve memorizzarlo: ogni editor di bundle ha una scheda "Dove viene mostrato" che indica il blocco giusto, più un link "Anteprima sul Suo tema live" che apre l'editor del tema con quel blocco già pronto per l'inserimento nel template corretto.

3Tour dell'app

L'app si trova sotto App → Combora. Il menu ha sei voci — Home, Bundle, Statistiche, Piani, Aiuto e Impostazioni — più la chat di assistenza, presente in ogni schermata:

Home

La schermata di benvenuto e il polso della Sua installazione. Mentre sta ancora configurando mostra una checklist in tre passaggi — creare il primo bundle, pubblicarlo e (se la Sua offerta è un regalo con l'acquisto) attivare il motore dei regali nel Suo tema. La checklist non è decorativa: ogni passaggio si spunta da solo solo quando è effettivamente avvenuto nel Suo negozio, il pulsante d'azione compare solo sul passaggio in sospeso, e se in seguito annulla la pubblicazione di tutto la checklist torna a riflettere la realtà. A completamento avvenuto, Home festeggia con un link diretto per visualizzare il Suo negozio (può chiudere l'avviso quando vuole).

Sotto la checklist: i Suoi bundle più recenti con il loro stato, una fascia di attenzione se un bundle necessita revisione (per esempio perché ha archiviato un prodotto che ne faceva parte — l'app lo rileva da sola e lo segnala senza annullare la pubblicazione di nulla), e una striscia con il Suo piano attuale.

Bundle

L'elenco di tutti i Suoi bundle: ricerca per nome, filtro per stato (Pubblicato / Bozza), azioni per riga (duplica, pubblica/sposta in bozza, elimina) e selezione multipla con azioni in blocco. Tutto viene creato da qui con Crea bundle.

Statistiche

Metriche di rendimento dei Suoi bundle sugli ordini reali: fatturato attribuito, % di ordini con un bundle, risparmio erogato, valore medio dell'ordine e un grafico temporale. Dettagli nella sezione 17.

Piani

Il Suo piano attuale e le opzioni di aggiornamento. Il piano Gratuito consente 3 bundle pubblicati alla volta; i piani a pagamento non hanno limiti (sezione 18).

Aiuto

Domande frequenti e spiegazioni dei concetti (arbitraggio tra bundle, regali, blocchi).

Diagnostica (una scheda dentro Aiuto)

Il pannello di salute e assistenza si trova come scheda dentro Aiuto (selettore "Guide | Diagnostica" in alto): controlli live dell'intera installazione, il registro eventi e il rapporto di assistenza che copia quando qualcosa va storto (sezione 19).

Chat di assistenza (bolla fluttuante)

Nell'angolo in basso a destra di ogni schermata c'è una bolla della chat 💬 per parlare con l'assistenza direttamente: conversazioni per argomento, cronologia, e un avviso se l'assistenza è disponibile o assente. Viene condiviso solo ciò che scrive Lei — mai i dati dei Suoi clienti.

Impostazioni

Lingua dell'app (7 lingue), Design del widget (il modello di stile per l'intero negozio — sezione 13), sincronizzazione manuale degli sconti e accesso sviluppatori.

4Anatomia dell'editor

Ogni tipo condivide lo stesso editor; cambia solo la sezione dei prodotti e del prezzo. Un bundle appena creato ha questo aspetto:

4.1 Informazioni di base

Nome del bundle

Interno. Lo vede solo Lei; serve per trovarlo nel Suo elenco.

Titolo sul negozio online

Ciò che il cliente vede come nome dell'offerta nel carrello e al checkout. È traducibile. È anche il testo della riga di sconto (troncato a 100 caratteri).

Testo del badge

Un badge breve facoltativo ("Miglior valore") che il Suo tema può mostrare come evidenza.

4.2 Pianificazione

Date di inizio e fine facoltative. Vuote = l'offerta va live alla pubblicazione e non scade mai. Un bundle pubblicato fuori dalla sua finestra smette di applicare lo sconto automaticamente e lo applica di nuovo una volta rientrato nella finestra, senza che Lei debba toccare nulla.

4.3 Prodotti

A seconda del tipo sceglie prodotti specifici (e, all'interno di ciascun prodotto, può selezionare solo alcune sue varianti) oppure una collezione. L'ambito "qualsiasi prodotto del negozio" esiste solo nel regalo con l'acquisto, come condizione. Il selettore è quello standard di Shopify:

4.4 Prezzo

Ogni tipo ha la propria sezione (percentuale, importo, prezzo fisso, fasce, premio…). È documentata nel capitolo di ciascun tipo. In ogni caso il prezzo addebitato viene calcolato da Shopify al checkout a partire dalla configurazione pubblicata: ciò che mostrano i blocchi è informativo.

4.5 Abbonamenti

Per impostazione predefinita un cliente non può acquistare un articolo del bundle in abbonamento (questo protegge il checkout da prezzi di abbonamento mescolati con sconti bundle). Nei tipi in cui ha senso (mix & match, componi la scatola e regalo con l'acquisto) c'è un'opzione avanzata, "Consenti abbonamenti in questo bundle (avanzato)"; attivandola l'editor mostra un avviso che ricorda cosa implica.

4.6 La barra laterale destra (e due sezioni del corpo)

Oltre a Salva (e Salva come bozza su un bundle non ancora pubblicato), con la barra Modifiche non salvate / Salva / Annulla in alto, l'editor organizza il resto così:

Stato + azione (barra laterale)

Pubblica (o Aggiorna bundle se è già pubblicato) e Sposta in bozza. Pubblicare rende l'offerta live; spostare in bozza la ritira mantenendo intatta l'intera configurazione.

Modalità test (corpo)

Selezioni "Pubblica in modalità test" per provare il bundle senza esporlo ai Suoi clienti. I widget si mostrano solo nell'editor del tema — apra lì il modello di prodotto e il bundle appare esattamente dove starà. Nel Suo negozio non compaiono mai, nemmeno tramite il link di anteprima di un tema bozza. Mentre il bundle è in modalità test lo sconto viene calcolato solo per i clienti con il tag combora-test; per tutti gli altri il bundle potrebbe anche non esistere. Per percorrere l'intero checkout, aggiunga quel tag al Suo cliente di prova (Admin → Clienti) e acceda al negozio online come lui. Deselezioni la casella e prema Aggiorna bundle e diventa live, applicandosi a chiunque soddisfi le condizioni. Nell'elenco, un bundle in modalità test porta il badge Modalità test.

Visibilità nel catalogo (corpo)

Solo bundle fissi: se il prodotto padre del bundle appare nel Suo catalogo o no (sezione 5).

Prima di pubblicare (barra laterale)

La checklist che blocca la pubblicazione finché non sono completati gli elementi essenziali (titolo, prodotti, prezzo…).

Cosa vede il Suo cliente (barra laterale)

Finché all'offerta manca ancora qualcosa, questa scheda spiega cosa manca e mostra un'anteprima del contenuto. Una volta completata l'offerta, la scheda lascia il posto alla vera anteprima del widget sotto Vedi anteprima. L'aspetto finale dipende dal Suo tema.

Stile anteprima (barra laterale, solo su bundle già creati)

Indica il design del widget attivo per questo bundle e offre Vedi anteprima (il widget a grandezza naturale in una finestra modale) e Personalizza design (lo studio di design di questo bundle: preset, ordine degli elementi e stile per elemento — sezione 13). Su un bundle appena creato compare dopo il primo salvataggio.

Dove viene mostrato (barra laterale)

Il blocco del tema che rende questo tipo e il link diretto all'editor del tema.

Un bundle con pianificazione mostra anche il badge della sua finestra (Pianificato / Attivo / Terminato) e il pulsante Rimuovi pianificazione per tornare ad "attivo alla pubblicazione".

4.7 Avvisi che l'editor può mostrare

• Sovrapposizione: se i prodotti del bundle sono già presenti in altri bundle pubblicati, un banner avverte: "Al checkout si applica solo la migliore offerta per riga: i bundle non si sommano". Non è un errore — è un'informazione (vedi sezione 14).
• Nessun risparmio / prezzo 0: in un bundle fisso con un prezzo bundle, se il prezzo scelto non fa risparmiare nulla (o è 0), l'editor lo segnala prima che Lei pubblichi.
• Gruppo vuoto: una collezione senza prodotti idonei viene mostrata come nota nell'anteprima e, se prova a pubblicare, come errore con la spiegazione.

4.8 Modificare un bundle pubblicato

Quando modifica un bundle pubblicato, le Sue modifiche vengono salvate senza raggiungere il Suo negozio. L'editor mostra la Sua modifica, i Suoi clienti continuano a vedere la versione pubblicata al prezzo pubblicato, e il bundle è contrassegnato come Modifiche non pubblicate nella Sua lista. Prema “Aggiorna bundle” per pubblicarle, o le scarti dall'avviso nell'editor. In questo modo può preparare le modifiche con calma. "Sposta in bozza" ritira l'offerta dal negozio online immediatamente; pubblicarla di nuovo la ripristina esattamente com'era.

5Bundle fisso

Un insieme chiuso di prodotti venduto come una singola unità. È l'unico tipo che crea anche un prodotto acquistabile con un clic nel Suo catalogo: un prodotto "padre" (un bundle nativo di Shopify) i cui componenti si espandono automaticamente al checkout.

5.1 Configurazione

1. Prodotti: aggiunga i componenti (varianti specifiche) e la quantità di ciascuno. Massimo 30 componenti per bundle.
2. Prezzo — due modalità che si escludono a vicenda:
   • Prezzo bundle fisso: digita il prezzo totale (per es. $1,299.00). Il risparmio viene calcolato rispetto alla somma dei componenti.
   • Applica uno sconto: una percentuale o un importo sulla somma dei componenti.
3. Visibilità nel catalogo: i bundle fissi sono prodotti Shopify reali, quindi decide se il bundle appare anche nel Suo catalogo oppure è raggiungibile solo dal widget:
   • Nascosto — solo dal widget (predefinito): il bundle non compare nelle collezioni, nella ricerca del negozio online o nei consigliati. La sua pagina prodotto resta attiva affinché il pulsante del widget funzioni.
   • Visibile — un normale prodotto del catalogo: compare nelle collezioni e nella ricerca come qualsiasi altro prodotto.
4. Pubblica. Alla pubblicazione, Combora crea (o aggiorna) il prodotto padre nel Suo catalogo — e, se il pack non ha ancora un'immagine, vi copia quella del primo componente, in ENTRAMBE le modalità di visibilità (un pack nascosto compare comunque nel carrello, al checkout e nelle email dell'ordine). Non sovrascrive mai un'immagine impostata da Lei; può cambiarla in qualsiasi momento sotto Admin → Prodotti.

5.2 Cosa vede il Suo cliente

5.3 Dettagli e limiti di questo tipo

• I componenti devono essere varianti con scorte disponibili; il prodotto padre eredita la disponibilità.
• Il prodotto padre si gestisce da solo: spostare il bundle in bozza o eliminarlo lo ritira dal negozio online (verificato durante la stesura di questo manuale). Non lo elimini manualmente.
• Per impostazione predefinita il padre è nascosto dal catalogo. Prima che esistesse questa opzione compariva in /collections/all come scheda senza immagine; i bundle già pubblicati sono stati portati automaticamente a "Nascosto". Se preferisce il comportamento precedente, lo imposti su Visibile.
• Massimo 30 componenti. Il prezzo fisso viene ripartito tra i componenti con arrotondamento esatto (la somma delle parti è sempre uguale al totale).
• Il bundle fisso si applica anche se il cliente aggiunge i componenti separatamente nelle quantità esatte — il checkout li raggruppa e sconta comunque allo stesso modo.

6Mix & match

Il cliente sceglie almeno N articoli da un gruppo e l'intero gruppo esce scontato.

6.1 Configurazione

1. Prodotti: il gruppo idoneo può essere prodotti specifici — selezionando, se vuole, solo alcune varianti di ciascuno all'interno del selettore — oppure una collezione (che si aggiorna da sola).
2. Quantità: il numero minimo di articoli per qualificarsi e, facoltativamente, un massimo (oltre il massimo, gli articoli in eccesso vengono pagati a prezzo pieno).
3. Sconto: una percentuale o un importo, applicato a ogni articolo idoneo nel carrello una volta raggiunto il minimo.

6.2 Cosa vede il Suo cliente

6.3 Dettagli di questo tipo

• Un carrello sotto il minimo non viene bloccato: il cliente paga il prezzo pieno finché non si qualifica.
• Con un massimo impostato, il selettore smette di accettare selezioni una volta raggiunto il limite, e nel carrello solo le prime unità fino al massimo vengono scontate.
• Le quantità si contano per unità: 3 unità dello stesso prodotto idoneo si qualificano anche per un minimo di 3.

7Sconto per volume

Fasce di prezzo per quantità: "compra almeno 2 → 10%, almeno 4 → 20%". La fascia viene decisa per prodotto: la quantità di ogni prodotto idoneo nel carrello determina la propria fascia, e la fascia raggiunta si applica alle unità di quel prodotto. Esempio con "4+ → 20%": 4 unità dello stesso snowboard → 20% di sconto su tutte e 4; ma 2 unità di uno snowboard + 2 di un altro → ogni prodotto rientra nella fascia 2+ (10%), non nella 4+. Le quantità di prodotti diversi non si sommano tra loro.

7.1 Configurazione

1. Prodotti: prodotti specifici o una collezione (come nel mix). Se vuole solo alcune varianti di un prodotto, le selezioni all'interno del selettore quando lo sceglie.
2. Fasce: ogni fascia è "Compra almeno N" + uno sconto (percentuale o importo). Ne aggiunga quante ne servono con "Aggiungi fascia" (fino a 50).

7.2 Cosa vede il Suo cliente

7.3 Dettagli di questo tipo

• Si applica solo la fascia più alta raggiunta (le fasce non si sommano).
• Le fasce possono mescolare tipi di valore (alcune %, altre importo).
• Un importo di sconto fisso viene ripartito tra le righe in modo proporzionale ed esatto.

8Compra X ricevi Y (BOGO)

Compra X unità e le successive Y unità arrivano con un premio. Il premio può essere gratuito (100%), una percentuale, un importo di sconto o un prezzo fisso per unità.

8.1 Configurazione

8.2 Cosa vede il Suo cliente

8.3 Dettagli di questo tipo

• L'offerta si ripete a blocchi interi: con "2+1", 6 unità = 2 gratis; 5 unità = 1 gratis.
• Il blocco del tema che lo rende è Combora volume table (presenta il "compra X ricevi Y" come una tabella di risparmio).
• Il premio "prezzo fisso" addebita esattamente quel prezzo per ogni unità premiata.

9Regalo con l'acquisto (GWP)

Aggiunge automaticamente un prodotto regalo (a $0.00) quando il carrello soddisfa la condizione, e lo rimuove se smette di soddisfarla. È il tipo più automatizzato: l'app embed Combora Gift gestisce il regalo senza che il cliente debba fare nulla.

9.1 Configurazione

1. Il regalo: una variante specifica che si aggiunge quando il cliente si qualifica.
2. Condizione di sblocco — quattro opzioni:
   • Per spesa minima: il carrello raggiunge un importo (per es. $1,000).
   • Per numero di articoli: raggiunge N unità.
   • Spesa e quantità (entrambe): sono richieste entrambe.
   • Portando una combinazione di prodotti: un elenco specifico di articoli (da 2 a 5; un'unità di ciascuno) che devono trovarsi tutti nel carrello.
3. Cosa conta ai fini della condizione: qualsiasi prodotto del negozio, prodotti specifici, o collezioni.

9.2 Cosa vede il Suo cliente

La barra ha quattro stati e, già dal carrello vuoto, nomina il regalo e ciò che conta: prima che il cliente inizi enuncia la regola ("spendi $1,000 su quello snowboard e ricevi la cera gratis"), a metà strada dice cosa manca, al superamento della soglia annuncia il regalo per nome, e se il cliente lo toglie a mano lo dice invece di restare su "in applicazione". Quando contano più di tre prodotti, la barra dice prodotti idonei e aggiunge un pannello "Quali prodotti contano?" che li elenca.

9.3 Dettagli e protezioni di questo tipo

• Il regalo stesso non conta ai fini della spesa qualificante.
• La soglia si misura sul prezzo di listino di ciò che conta, non su quello che il cliente finisce per pagare: un'altra offerta che sconta quelle stesse righe non la intacca mai. Barra, regalo automatico e checkout leggono lo stesso numero.
• Se il cliente rimuove il regalo a mano, l'app rispetta la scelta e non lo riaggiunge in quella sessione; la barra del carrello lo dice esattamente ("Regalo rimosso") invece di restare su "in applicazione".
• Se ritira l'offerta (sposta in bozza, fine della finestra) mentre ci sono carrelli aperti che già avevano il regalo, il motore rimuove da solo quella riga orfana non appena il carrello si aggiorna di nuovo — non si trasforma mai in un addebito.
• Se il regalo esaurisce le scorte, l'offerta semplicemente non lo aggiunge (non blocca l'acquisto).
• Protezione anti-addebito: una validazione al checkout impedisce di pagare per un regalo che è contrassegnato come tale ma è arrivato con un prezzo — il cliente non paga mai per errore un articolo segnato come regalo. La validazione agisce solo al checkout, mai durante la navigazione.
• Quando "cosa conta" sono le collezioni, l'app risolve i prodotti della collezione al momento della pubblicazione (e li aggiorna ogni notte, o subito se ripubblica — le due velocità della sezione 4.3), così la barra di progresso e il regalo automatico funzionano proprio come con prodotti specifici. L'unica eccezione: una collezione enorme (oltre ~150 prodotti) non può essere prevista dal browser — la barra non viene mostrata per quell'offerta, ma il regalo e il prezzo restano corretti (li decide il server).
• Un regalo il cui "cosa conta" è qualsiasi prodotto del negozio può essere pubblicizzato con il blocco Combora gift offer su ogni pagina prodotto: quando sceglie quell'ambito, l'editor mostra la casella "Mostra questa offerta regalo su ogni pagina prodotto". Disattivata (l'impostazione predefinita), l'offerta è visibile solo nel carrello — la barra di progresso e il regalo automatico funzionano allo stesso modo; attivata, viene anche pubblicizzata con una scheda su ogni pagina prodotto (l'offerta non ha prodotti specifici da selezionare, quindi il blocco la legge dall'indice pubblicato del negozio). L'eccezione deliberata resta la pagina del prodotto regalo stesso: un premio non è un'esca.

10Componi la scatola

Il cliente riempie una scatola di dimensione fissa (per es. 3 articoli) con ciò che sceglie da un gruppo. Ogni scatola completa viene addebitata con uno sconto o a un prezzo scatola chiuso.

10.1 Configurazione

10.2 Cosa vede il Suo cliente

Usa lo stesso blocco Combora mix & match e lo stesso selettore con contatore della sezione 6: "seleziona 3", un contatore di progresso, una CTA con la quantità. La differenza è il calcolo: qui le scatole vengono addebitate per scatola completa — con una scatola da 3, sei articoli sono due scatole; sette articoli sono due scatole più un articolo a prezzo pieno.

10.3 Dettagli di questo tipo

• Gruppo idoneo: prodotti specifici (con le loro varianti, se ne seleziona solo alcune) o una collezione (il selettore visivo compare con ogni ambito, come nel mix — con le collezioni l'elenco viene risolto al momento della pubblicazione e aggiornato ogni notte).
• Il prezzo scatola viene ripartito tra gli articoli in modo esatto; con valute a 0 decimali (JPY) o a 3 decimali (BHD) la ripartizione rispetta la valuta.
• Supporta l'opzione abbonamenti (sezione 4.5).

11Complementi (acquistati spesso insieme)

Un prodotto principale suggerisce prodotti complementari; se il cliente prende l'insieme, ottiene uno sconto. È il classico "acquistati spesso insieme" sulla pagina prodotto.

11.1 Configurazione

11.2 Cosa vede il Suo cliente

11.3 Dettagli di questo tipo

• Lo sconto si applica una volta che il prodotto principale e almeno un complemento sono nel carrello; copre le righe dell'insieme.
• Il blocco può essere aggiunto anche al template del carrello come ultimo spunto di cross-sell.
• I complementi esauriti appaiono disabilitati con il relativo avviso, e non sono mai preselezionati.

12Combo

Il tipo avanzato: combina due o più sotto-offerte (di qualsiasi altro tipo) in un unico bundle. La differenza chiave rispetto alla pubblicazione di bundle separati: all'interno di un combo le sotto-offerte si sommano — il cliente può ottenere lo sconto per volume e il regalo allo stesso tempo.

12.1 Configurazione

Ogni riga si espande sul posto con lo chevron, e la sotto-offerta si modifica in linea: i suoi prodotti, le sue fasce o il suo premio. Ogni sotto-offerta influisce solo sui propri prodotti.

12.2 Cosa vede il Suo cliente

Un combo non viene promosso come scheda nel blocco Combora bundle: quel blocco elenca i bundle fissi, che hanno un prezzo e un pulsante, e un combo non ha né l'uno né l'altro. Ogni sotto-offerta viene promossa dal proprio blocco — la tabella volume per una sotto-offerta di volume, la barra regalo per una di regalo — e il combo mostra il suo effetto completo nel carrello, dove ogni parte agisce con il proprio badge: lo sconto per volume sulle sue righe e il regalo aggiunto automaticamente a $0.00.

Misurato nel negozio demo su un combo che somma "2 o più di questo snowboard → 15% di sconto" e "un berretto in regalo appena si arriva a $900.00 di quello snowboard": due snowboard passano da $1,040.00 a $850.00 — il 15% e il berretto a $0.00 — e tre passano da $1,540.00 a $1,275.00. Due bundle separati non farebbero mai entrambe le cose sulla stessa riga; dentro un combo le sotto-offerte si sommano (sezione 14).

12.3 Dettagli di questo tipo

• Le sotto-offerte si sommano all'interno del combo, ma il combo compete come un tutt'uno contro gli altri bundle secondo la regola della migliore offerta per riga.
• Il regalo in una sotto-offerta GWP usa lo stesso motore di aggiunta automatica del tipo regalo.
• Limite di dimensione: l'insieme appiattito dei prodotti del combo non può superare 50 voci (l'editor lo mostra: "Uses X of 50").
• L'editor ha una finestra modale "Come funzionano i combo" con un esempio guidato, e ogni sotto-offerta definisce "Prodotti a cui si applica questa offerta" — una sotto-offerta senza prodotti specifici mostra un avviso perché non potrà applicare alcun prezzo.
• Una sotto-offerta BOGO all'interno di un combo offre un premio in percentuale o importo (il "prezzo fisso per unità" è esclusivo del BOGO autonomo).

13Progettare il widget

I blocchi di Combora vengono forniti con un aspetto adatto a qualsiasi tema, ma può progettarli dall'app, senza toccare il CSS: scegliere uno stile, riordinare e nascondere elementi, e regolare colori, dimensioni e forme elemento per elemento. Il tutto con un'anteprima che usa lo stesso motore di rendering del Suo negozio online, quindi ciò che vede è ciò che viene pubblicato.

13.1 Due luoghi in cui progettare

Un bundle che non ha ancora toccato nulla mostra l'avviso "Questo bundle segue il template widget del Suo negozio". Non appena sceglie lì un preset, quel bundle prende una strada propria.

13.2 Gli stili (preset)

Template del negozio

Solo nel design di un bundle: segue quanto definito in Impostazioni. È il valore di partenza. Se non esiste ancora un template, si applicano le impostazioni del blocco nell'editor del tema.

Editor del tema

Prevalgono le impostazioni proprie del blocco nel Suo editor del tema (accento, angoli, modalità stile). Questo è il comportamento classico, quello che aveva prima che esistesse lo studio.

Combora

Il look curato di Combora: una scheda con sfondo, bordi e ombre propri. Coerente in qualsiasi tema.

Come il tema

Decorazione minima: dominano la tipografia e i colori del Suo tema. Per temi con una forte personalità.

Senza stile

Markup pulito, nessuna decorazione, così il Suo sviluppatore può scrivere il proprio CSS (editor del tema → CSS personalizzato). Gli aggancio sono la classe .combora-w e le variabili --combora-*.

Personalizzato

Apre i controlli sottostanti: layout, stile globale e regolazione fine per elemento.

13.3 Layout: riordinare e nascondere

Con il preset Personalizzato, compare Layout: un elenco degli elementi del widget che può trascinare (o spostare con le frecce) per cambiarne l'ordine, più un'icona a occhio per nascondere quelli facoltativi.

Gli elementi dipendono dal tipo di bundle, perché ogni tipo disegna un widget diverso:

13.4 Stile globale e regolazione fine

Stile globale è ciò che cambia l'intero widget in una volta: colore accento, sfondo scheda, colore testo, angoli (netti / morbidi / arrotondati), ombra (nessuna / leggera / media) e densità.

Regolazione fine per elemento apre ogni elemento separatamente — titolo, prezzo, risparmio, badge, pulsante, scheda, miniature, etichette — con ciò che ha senso per ciascuno: dimensione, peso, colore, maiuscolo, padding, forma, colore del bordo, colore del prezzo barrato… Ogni controllo ha un "Torna al tema" per annullare solo quella regolazione, e in fondo c'è un "Ripristina tutta la personalizzazione".

• Se non definisce il Risparmio, segue lo stile del Badge.
• Il colore del testo del pulsante non è selezionabile: viene derivato automaticamente per contrasto rispetto allo sfondo scelto, così non può mai risultare illeggibile.
• I valori sono limitati a intervalli sensati: non può digitare una dimensione che rompa il widget su mobile.

13.5 L'anteprima (e cosa NON è)

A destra c'è un pannello contrassegnato "Solo anteprima". La differenza conta:

• Sinistra = il Suo design. Ciò che regola lì viene salvato e va al negozio online.
• Destra = la lente. Sfondo dell'anteprima (chiaro / scuro / un colore personalizzato), dimensione base del testo, larghezza dello slot (una colonna prodotto stretta rispetto a una sezione ampia) e un'approssimazione della Sua tipografia. Serve a verificare che il Suo design regga in luoghi diversi. Non cambia nulla nel Suo negozio o nel Suo design.

E nella barra laterale dell'editor del bundle, la scheda "Stile anteprima" Le dice quale design è attivo ("Active design: Combora") e offre due pulsanti: Vedi anteprima, che apre il widget a grandezza naturale in una finestra modale ("This is how it will look in your store"), e Personalizza design, che entra nello studio di questo bundle. La tipografia e lo sfondo reali provengono dal Suo tema, quindi per il via libera definitivo guardi il widget nell'editor del tema.

14Combinare i bundle tra loro

Può pubblicare tutti i bundle che il Suo piano consente, anche sugli stessi prodotti. Le regole di convivenza sono fisse e prevedibili:

1. La migliore offerta per riga. Per ogni articolo del carrello, Shopify applica l'offerta che sconta di più quell'articolo. Due bundle non si sommano mai sulla stessa riga.
2. Bundle diversi possono coesistere nello stesso carrello — ciascuno sulle proprie righe. Uno sconto mix sugli snowboard e un regalo basato sulla spesa possono applicarsi contemporaneamente perché agiscono su righe diverse.
3. In caso di parità, vince il bundle più vecchio (il primo che ha creato).
4. L'eccezione è il combo: le sue sotto-offerte si sommano tra loro (sezione 12).

E gli sconti che non sono di Combora? La regola sopra governa i pack di Combora tra loro. Con gli sconti di terzi decide Shopify, e lo abbiamo verificato in un negozio reale: due sconti prodotto (un pack Combora e un Suo sconto automatico o codice prodotto) non si sommano mai sullo stesso articolo — Shopify applica solo il maggiore dei due, anche se entrambi sono marcati come combinabili; possono convivere su righe diverse dello stesso ordine. Uno sconto ordine (per esempio un codice del −10% su tutto l'ordine) si sottrae invece dopo, sui prezzi già scontati — il comportamento standard di Shopify con qualsiasi app.

Un esempio numerico reale (verificato nel negozio)

Nel negozio demo un prodotto appartiene di proposito a due bundle: lo snowboard che è componente del bundle fisso è anche il soggetto di quello per volume. Da solo prende il livello di volume che la sua quantità gli vale; insieme all'altro componente del bundle fisso, nelle quantità esatte, anche il bundle fisso entra come candidato e la riga si tiene la migliore delle due. Stesso prodotto, due bundle, un prezzo per riga — mai entrambi.

15Creazione in blocco

Dalla galleria Crea bundle ci sono due flussi per creare molti bundle in una volta. Entrambi creano bozze: nulla raggiunge il negozio online finché non le rivede e pubblica.

15.1 Genera da una collezione

1. Scelga la collezione.
2. Scelga il template: "Un multipack per prodotto" (un bundle fisso da N unità per ogni prodotto) oppure "Un unico bundle per l'intera collezione".
3. Configuri unità e sconto, poi prema Crea bozze.

Che cosa crea davvero ciascun template

Un multipack per prodotto percorre la collezione e crea una bozza di bundle fisso per prodotto: N unità della prima variante di quel prodotto (ordine di posizione), con lo sconto scelto applicato alla somma. Ogni bozza è un normale bundle fisso — la apra per cambiare la variante, passare a un prezzo bundle chiuso, aggiungere un badge… — e quando la pubblica diventa a sua volta un prodotto acquistabile con un clic, come qualsiasi bundle fisso (sezione 5).

Un unico bundle per l'intera collezione crea esattamente una bozza del tipo flessibile che Lei sceglie (volume, mix & match, componi la scatola o compra X ricevi Y) il cui gruppo idoneo è la collezione stessa. L'appartenenza segue il Suo catalogo: il gruppo viene risolto quando pubblica e aggiornato ogni notte (o subito se ripubblica), così i prodotti che aggiunge alla collezione in seguito entrano nell'offerta senza toccare il bundle.

I prodotti vengono saltati, e il banner del risultato glielo comunica, quando non sono Attivi nel Suo catalogo, quando non hanno nessuna variante acquistabile — e quando sono essi stessi prodotti pack di Combora: un pack generato non annida mai un altro pack.

Esempi svolti

La stessa schermata, sette configurazioni ed esattamente ciò che ciascuna produce:

15.2 Importa da un CSV

Per cataloghi ampi o per migrare da un'altra app. La pagina include il riferimento completo del formato, un template scaricabile con un esempio per tipo e un pulsante di esportazione (scarica tutti i Suoi bundle nello stesso formato, pronti per essere reimportati in un altro negozio).

• Tipi importabili: fixed, volume, mix_and_match, build_a_box, bogo (i tipi con un regalo, un'ancora o sotto-offerte si creano nell'editor).
• Riferimenti per handle di prodotto o collezione, o per GID di Shopify.
• In components (solo fisso): handle:quantity separati da |.
• Fino a 200 righe per importazione; un file più grande viene troncato e l'app glielo comunica.

16Gestione quotidiana

16.1 L'elenco

Ricerca per nome, filtro per stato e, su ogni riga: Duplica (crea una copia in bozza), Pubblica / Sposta in bozza ed Elimina. La data su ogni riga è l'ultimo aggiornamento (al passaggio del mouse compare il tooltip).

16.2 Azioni in blocco

16.3 Il ciclo di vita di un bundle

Bozza

Invisibile per il negozio online. Modificabile senza limiti.

Pubblicato

L'offerta è attiva (entro la sua finestra di pianificazione). Modificarla non cambia nulla in tempo reale finché non preme Aggiorna bundle.

Sposta in bozza

Ritira l'offerta immediatamente; la configurazione resta intatta così può ripubblicarla.

Elimina

Elimina il bundle e ritira il suo sconto (e il prodotto padre, se era un bundle fisso). Non può essere annullato. Le statistiche sugli ordini passati vengono mantenute.

16.4 Cosa fa Combora da sola, mentre Lei dorme

Quattro processi automatici mantengono il Suo negozio aggiornato senza che Lei debba fare nulla. Non deve configurarli né sorvegliarli — sono documentati qui perché sappia perché le cose si sistemano da sole:

17Statistiche

Se vende in più valute, un selettore di valuta si trova accanto alle metriche: gli importi vengono mostrati nella valuta scelta (i contatori degli ordini sono globali).

Sotto le metriche ci sono tre grafici per l'intervallo scelto, tutti con un punto al giorno e un tooltip:

• Ordini con un bundle nel tempo — barre, con il valore stampato sopra le barre che hanno dati.
• Fatturato attribuito al giorno — una linea, per vedere la tendenza.
• Risparmio erogato al giorno — barre: quanto sconto hanno dato i Suoi bundle ogni giorno.

18Impostazioni e piani

18.1 Impostazioni

• Lingua dell'app: 7 lingue (inglese, spagnolo, francese, tedesco, italiano, portoghese, olandese). Riguarda l'admin; ciò che vede il Suo cliente segue la lingua del Suo tema/mercato.
• Design del widget: Modifica template widget apre lo studio di design per l'intero negozio — lo stile che ogni bundle eredita (sezione 13). Salvare qui risincronizza i bundle pubblicati.
• Sincronizza sconti: non deve premerlo — tutto si sincronizza da solo quando pubblica. È presente come rete di sicurezza: se un bundle smettesse di scontare, questo rigenera lo sconto Shopify da tutti i Suoi bundle pubblicati. È sicuro usarlo quanto vuole, e se non c'era nulla da correggere lo dice: Tutto era già aggiornato.
• Accesso sviluppatori: i dati pubblici che il Suo tema può leggere (appendice 22). La documentazione del contratto è aperta su ogni piano.

18.2 Piani

Prezzi fissi: non prendiamo mai una percentuale delle Sue vendite, e il prezzo non dipende dal Suo piano Shopify — un negozio Basic e un negozio Plus pagano lo stesso.

• Gratuito ($0/mese): fino a 3 bundle pubblicati alla volta (le bozze non contano) con tutti gli 8 tipi inclusi. Quando prova a pubblicare il 4°, l'app lo blocca con l'avviso corrispondente: ne sposti un altro in bozza o passi a un piano superiore. Nel piano gratuito, i blocchi mostrano un discreto badge Powered by Combora.
• Pro ($14.99/mese): bundle pubblicati illimitati e nessun badge.
• Plus ($39.99/mese): tutto ciò che offre Pro, più assistenza prioritaria, importazione/esportazione CSV in blocco (fino a 200 bundle per file) e supporto all'integrazione diretta per il Suo sviluppatore (negozi headless e temi personalizzati).

La fatturazione passa da Shopify (Managed Pricing) — si gestisce e si annulla dalla pagina Piani stessa. I piani a pagamento includono una prova gratuita di 7 giorni, e se annulla mantiene il piano fino alla fine del ciclo già pagato. I negozi fondatori (le prime 100 installazioni) mantengono il prodotto completo gratis per sempre.

19Diagnostica e assistenza

Diagnostica (la seconda scheda di Aiuto) è la prima tappa quando qualcosa non torna — ed è ciò che l'assistenza Le chiederà se apre un ticket. Combora registra automaticamente, per ogni negozio, tutto ciò che fallisce sotto il cofano (sul server e nel Suo negozio online) anche quando il cliente non lo vede mai, e questo pannello lo rende accessibile. Non memorizza alcun dato dei clienti.

19.1 Controlli di salute

Lo stato live di ciò che l'assistenza chiede per prima cosa, verificato con Shopify a ogni caricamento:

19.2 Registro eventi

Ogni voce è qualcosa che è successo ed è stato registrato: un errore durante la pubblicazione, un regalo che Shopify ha rifiutato di aggiungere (con il motivo esatto), uno sconto in collisione con un altro, un webhook fallito… Filtri per livello (Informazione = previsto ma rilevante, come il limite del piano; Avviso; Errore) e per area (pubblicazione, sconti, piano e fatturazione, negozio online, sincronizzazione…). Un registro vuoto è un buon segno: si riempie solo quando qualcosa va storto. Gli eventi vengono conservati per 30 giorni.

19.3 Il rapporto di assistenza

Un unico documento con tutto il necessario per diagnosticare il Suo negozio in un colpo solo: i controlli di salute, il Suo piano e la configurazione (senza dati sensibili), lo stato di pubblicazione di ogni bundle e gli eventi più recenti. Quando contatta l'assistenza, prema Copia rapporto (o Scarica come file) e lo allega al ticket — con questo, chi La assiste vede esattamente cosa è successo senza chiedere screenshot o accesso.

• Il rapporto non include nessun dato dei clienti né chiavi: solo lo stato, la configurazione dei bundle e gli eventi tecnici.
• Se il pulsante di copia non funziona nel Suo browser, il testo resta selezionato — prema Ctrl+C (Cmd+C su Mac) — oppure usi lo scarico.

20Limiti e regole importanti

Il riferimento unico per i limiti, verificato rispetto al codice dell'app:

Regole sul denaro (sempre esatte)

• Le percentuali troncano lo sconto per difetto (non viene mai arrotondato a favore di un addebito maggiore).
• Gli importi e i prezzi fissi vengono ripartiti tra le righe con un resto esatto: la somma delle parti è sempre uguale al totale.
• I decimali dipendono dalla valuta del Suo negozio (JPY senza decimali, BHD con tre…) — due decimali non vengono mai dati per scontati.
• Il prezzo addebitato viene calcolato da Shopify al checkout a partire dalla configurazione pubblicata. Ciò che mostrano i blocchi del tema è informativo.

Multi-valuta (Shopify Markets)

Se vende in più valute, non c'è nulla da configurare: definisce prezzi, soglie e sconti nella valuta del Suo negozio, e Combora fa il resto. Un cliente che acquista in un'altra valuta vede gli importi del widget convertiti nella propria (la soglia del regalo, il prezzo bundle, il risparmio di ogni fascia), e al checkout lo sconto viene convertito al tasso di cambio di Shopify del momento — lo stesso che converte i prezzi dei Suoi prodotti. La regola d'oro resta valida: ciò che il cliente vede pubblicizzato è esattamente ciò che il checkout gli addebita, nella sua valuta.

Altre regole

• Gli abbonamenti sono bloccati sulle righe bundle a meno che non attivi esplicitamente l'opzione (sezione 4.5).
• Un regalo GWP non viene pubblicizzato sulla pagina del prodotto regalo stesso (un premio non è un'esca).
• I bundle pubblicati fuori dalla loro finestra di pianificazione non applicano alcuno sconto (si riattivano da soli).

21Risoluzione dei problemi

Non riesco a vedere l'offerta sul mio negozio online

① Il bundle è Pubblicato (non una bozza) ed entro la sua finestra di date? ② Ha aggiunto il blocco giusto al template (la scheda Dove viene mostrato nell'editor)? ③ Se ha modificato un bundle pubblicato, ha premuto Aggiorna bundle?

Il regalo non si aggiunge da solo

① L'app embed Combora Gift è attivata? ② Il carrello soddisfa la condizione contando solo ciò che si qualifica (il regalo non conta)? ③ Il cliente lo ha rimosso a mano in questa sessione? ④ Il regalo è disponibile?

Lo sconto nel carrello non è quello che mi aspettavo

Ricordi la regola: solo la migliore offerta per riga. Se due bundle competono per lo stesso articolo, vince quello che sconta di più (e in caso di parità, il più vecchio). La somma avviene solo all'interno di un combo.

L'app dice: Hai un altro sconto automatico attivo

Questa è un'informazione, non un errore. Significa che ha propri sconti automatici sui prodotti in Shopify. Dove un bundle Combora e uno di quegli sconti ricadono sullo stesso prodotto, Shopify applica solo il migliore dei due — sommare due sconti prodotto sullo stesso articolo richiede Shopify Plus. Questa è una regola di Shopify, non di Combora. I Suoi bundle si combinano con i Suoi sconti su ordine e spedizione, e con gli sconti prodotto che ricadono su altri prodotti. L'avviso indica lo sconto sovrapposto specifico così sa quale controllare.

Ho pubblicato e dice limite del piano

Il piano Gratuito consente 3 bundle pubblicati alla volta. Ne sposti un altro in bozza o passi a un piano superiore.

La barra di progresso del regalo non appare

Viene renderizzata nel template del carrello (il blocco Combora gift progress) e solo per offerte il cui criterio può essere valutato nel browser. Con le collezioni come ciò che conta funziona comunque, perché l'app risolve i prodotti della collezione quando pubblica; l'unica eccezione è una collezione molto grande (oltre ~150 prodotti), dove la barra non viene mostrata anche se il regalo funziona comunque.

Il selettore con caselle non appare in mix / scatola

Il selettore compare con qualsiasi ambito: con varianti specifiche mostra esattamente quelle caselle, e con prodotti o una collezione l'elenco viene risolto quando pubblica (e aggiornato ogni notte, o subito se ripubblica). Se resta comunque vuoto, il gruppo idoneo non ha prodotti acquistabili — controlli la nota di anteprima nell'editor. In ogni caso il cliente può aggiungere prodotti come al solito e lo sconto scatta al qualificarsi.

Errori durante l'importazione di un CSV

Ogni riga fallita viene elencata con il suo motivo. Corregga quelle righe e riesegua solo con quelle — le righe corrette sono già state create.

Sospetto che uno sconto sia rimasto orfano

Impostazioni → Sincronizza sconti ripara lo stato. Non modifichi mai manualmente lo sconto Combora nella sezione Sconti di Shopify.

22Appendice per sviluppatori: il contratto pubblico

Combora pubblica i dati dei Suoi bundle nel Suo negozio come metaobject e metafield sotto il namespace combora, leggibili pubblicamente dal negozio online. Qualsiasi sviluppatore può costruire una UI completamente personalizzata leggendo questi dati da Liquid o dalla Storefront API — senza chiamare nessuna delle API dell'app. Questo contratto è versionato e solo additivo (versione attuale: public.v1): i campi esistenti non vengono mai rinominati o ritipizzati.

22.1 Cosa viene creato all'installazione

L'installazione predispone le definizioni (gli schemi) — visibili sotto Impostazioni → Metafield e metaobject e sotto Contenuto → Metaobject:

• Metaobject: combora_bundle (il bundle), combora_component (ogni riga componente) e combora_tier (ogni fascia di volume/soglia). Tutti e tre con accesso PUBLIC_READ dal negozio online, pubblicabili e traducibili.
• Metafield del negozio: combora.index e combora.manifest (JSON, lettura pubblica), e combora.all_pdp_gwps (list.metaobject_reference → combora_bundle): i regali per l'intero negozio che hanno scelto di essere pubblicizzati su ogni pagina prodotto.
• Metafield prodotto: combora.bundles (list.metaobject_reference → combora_bundle) — l'indice inverso prodotto → i suoi bundle.

22.2 Cosa succede alla pubblicazione / aggiornamento / ritiro

22.3 combora_bundle campo per campo

22.4 Il descrittore eligible

Il gruppo idoneo del bundle, con la stessa struttura per ogni tipo:

{ "mode": "all" | "products" | "collections" | "variants",
  "variants":   ["gid://shopify/ProductVariant/…"],
  "products":   ["gid://shopify/Product/…"],
  "collections":["gid://shopify/Collection/…"],
  "resolved_count": 12, "total_count": 12, "truncated": false }

Sono incluse solo le liste non vuote. Le tre chiavi di risoluzione sono informative (sui gruppi di collezione dicono quanti membri sono stati materializzati e se lo snapshot è stato troncato) — può ignorarle. Attenzione alla convenzione: il config del metaobject usa snake_case (gift_variant, min_qty), mentre l'oggetto gwp nell' index usa camelCase (giftVariant, minQty) — gli stessi dati su due superfici diverse.

Attenzione: i figli role:"option" di un gruppo di collezione sono uno snapshot preso al momento della pubblicazione; l'appartenenza live (e il prezzo) viene sempre risolta dalla Function al checkout.

22.5 combora.index e combora.manifest

shop.metafields.combora.index — la tabella di instradamento dei bundle pubblicati (esiste perché Lei non debba mai iterare metaobjects.combora_bundle.values, che Liquid tronca silenziosamente a 50):

{ "schema": 1, "revision_highwater": 128, "generated_at": "…",
  "bundles": [
    { "id": "f3062319-9d6e-…", "handle": "combora-bundle-f3062319-9d6e-…", "type": "fixed",
      "gid": "gid://shopify/Metaobject/…", "status": "active", "revision": 42 }
  ] }

id è un identificatore testuale, non un numero. Vengono annunciati solo i bundle pubblicati ed entro la loro finestra di pianificazione, così l'indice resta allineato al prezzo del checkout. Alcune voci portano campi extra: gwp (l'offerta regalo, solo sui bundle di tipo regalo), gwps (le offerte regalo di un combo, nell'ordine delle sotto-offerte) e test (true se il bundle è in modalità test: il JS del negozio online lo salta sul tema pubblicato).

shop.metafields.combora.manifest — il descrittore del contratto che uno strumento legge una volta sola: contract_version, schema_version, il contatore dei bundle e i GID delle tre definizioni. Può portare powered_by_badge: true, che è ciò che accende il badge Powered by Combora nei blocchi (solo sui negozi con piano Gratuito; altrove il campo viene omesso).

22.6 Leggerlo da Liquid

{%- comment -%} On a product page: the bundles for THIS product {%- endcomment -%}
{%- for bundle in product.metafields.combora.bundles.value -%}
  <h3>{{ bundle.title.value | escape }}</h3>
  {%- if bundle.badge_label.value != blank -%}
    <span class="badge">{{ bundle.badge_label.value | escape }}</span>
  {%- endif -%}
  <ul>
    {%- for component in bundle.components.value -%}
      {%- comment -%} label is optional: if missing, it falls back to the variant title and
          then to the product title. CAREFUL: if the product is NOT published to the Online
          Store channel, its reference does not resolve in Liquid and ALL the fallbacks
          return blank — guard the final name or you will render an empty "1× ". {%- endcomment -%}
      {%- assign name = component.label.value -%}
      {%- if name == blank -%}{%- assign name = component.variant.value.title -%}{%- endif -%}
      {%- if name == blank or name == 'Default Title' -%}{%- assign name = component.variant.value.product.title -%}{%- endif -%}
      {%- if name != blank -%}
        <li>{{ component.quantity.value }}× {{ name | escape }}</li>
      {%- endif -%}
    {%- endfor -%}
  </ul>
{%- endfor -%}

{%- comment -%} Or by direct handle, in any template {%- endcomment -%}
{%- assign bundle = metaobjects.combora_bundle['combora-bundle-{id}'] -%}

Entrambe le vie sono letture delimitate (l'elenco proprio del prodotto, o un handle diretto) — mai il .values globale. Due insidie di Liquid che Le fanno risparmiare un pomeriggio: (1) un for su un elenco di riferimenti tronca silenziosamente a 50 — i bundle di Combora non ci arrivano mai (il limite più alto è di 50 voci totali), ma non iteri le collezioni altrui dando per scontato di vederle tutte; (2) i campi facoltativi (label, badge_label, cta_label) spesso arrivano vuoti — protegga con != blank come sopra.

22.7 Leggerlo dalla Storefront API (localizzata)

query BundleByHandle @inContext(language: FR) {
  metaobject(handle: { type: "combora_bundle", handle: "combora-bundle-{id}" }) {
    title:       field(key: "title")       { value }
    badge_label: field(key: "badge_label") { value }
    components:  field(key: "components") {
      references(first: 25) {
        nodes { ... on Metaobject {
          label:    field(key: "label")    { value }
          quantity: field(key: "quantity") { value }
        } }
      }
    }
  }
}

@inContext restituisce le traduzioni seminate dall'app; ciò che non è tradotto ricade automaticamente sulla lingua di base.

22.8 Cosa può costruire con questo

• Una UI bundle completamente personalizzata nel tema, senza i blocchi di Combora, leggendo titolo, badge, componenti e risparmio dal metaobject.
• Una landing page di campagna: una pagina che elenca i bundle attivi da combora.index e ne renderizza ognuno per handle.
• Headless / Hydrogen: la stessa lettura sulla Storefront API con localizzazione per mercato.
• Integrazioni (feed, app di raccomandazione): il manifest dichiara la versione del contratto e dove si trova tutto.

22.9 Regole per lo sviluppatore

• Il prezzo appartiene alla Function. I campi del metaobject servono per la visualizzazione: non sommi il discount_value di un combo né ricalcoli i prezzi nel tema — il checkout è l'autorità.
• Solo additivo: possono comparire nuovi campi; quelli esistenti non cambiano. Scriva letture che tollerino campi sconosciuti.
• Combo: raggruppi i figli per position diviso 1000 (ogni sotto-offerta occupa una fascia di 1000) o per config.of[].index — mai per role, che può ripetersi.
• Stile: se costruisce la propria UI, ignori style e scriva il Suo CSS. Se invece vuole rispettare il design che il commerciante ha scelto nell'app, copi style.vars nell'attributo style della Sua radice e style.mode_class come classe; il preset Senza stile dello studio esiste esattamente per il caso opposto (markup pulito, il Suo CSS, con .combora-w e le variabili --combora-* come aggancio).
• Privato ≠ contratto: i metafield $app:runtime, $app:fnvars e $app:validation dello sconto sono interni alle Function, non hanno accesso dal negozio online, e la loro struttura può cambiare senza preavviso. Non ci costruisca sopra.
• Multi-valuta (Shopify Markets): ogni importo nel contratto — config.price, threshold, fixed_amount.amount, box_price — è sempre nella valuta del negozio, in unità minori. Se il Suo negozio vende in più valute, converta al momento della presentazione (in Liquid, moltiplichi per cart.currency.rate; in JS, per Shopify.currency.rate) prima di formattare; renderizzare il numero grezzo con la valuta di presentazione dell'acquirente mostra un prezzo sbagliato. Lo sconto reale al checkout viene calcolato dall'app ed è sempre corretto — questa regola riguarda solo ciò che il Suo widget mostra.
• Non scriva nel namespace combora. Shopify Le dà accesso in scrittura (è il Suo negozio), ma l'app lo rigenera a ogni pubblicazione e una revisione notturna ripristina i campi che governano il piano. Ciò che è Suo va nel Suo namespace.
• Questa appendice è il riferimento completo del contratto per gli sviluppatori esterni. Se manca qualcosa e Le serve, ci scriva tramite la chat dell'app o all'assistenza e lo documenteremo.

23Appendice per sviluppatori: un widget per tipo, in Liquid

L'appendice precedente descrive che cosa contiene il contratto; questa mostra come renderizzare ogni tipo di bundle con esso. Tutto il codice qui sotto legge soltanto il contratto pubblico — nessuna API dell'app, nessuno dei blocchi propri di Combora — quindi può incollarlo in uno snippet o in un blocco Liquid personalizzato nel template di prodotto e adattare il markup liberamente. Tre regole valgono per tutto ciò che c'è in questa pagina:

• Il prezzo appartiene alla Function. Tutto ciò che vede qui è visualizzazione; l'importo effettivamente addebitato viene calcolato dalla Shopify Function di Combora al checkout. Non ricalcoli mai un totale presentandolo come il prezzo.
• Gli importi sono unità minori nella valuta del negozio. Moltiplichi per cart.currency.rate prima di formattare, o un acquirente che naviga in un'altra valuta vedrà un numero sbagliato.
• I campi facoltativi arrivano spesso vuoti. Protegga con != blank — compreso il nome del componente dopo i suoi fallback (vedi 22.6).

23.1 Lo scheletro in cui si innesta ogni esempio

Una card per ogni bundle del prodotto corrente, con titolo, badge e il risparmio così come il bundle lo esprime (discount_value in basis point o unità minori). Ogni tipo renderizza poi il proprio corpo dentro il case:

{%- liquid
  assign bundles = product.metafields.combora.bundles.value
  assign rate = cart.currency.rate | default: 1
-%}

{%- if bundles != blank -%}
  {%- for bundle in bundles -%}
    {%- liquid
      assign type = bundle.bundle_type.value
      assign dv = bundle.discount_value.value
      assign cfg = bundle.config.value
    -%}
    <article class="cx__card">
      <h3>{{ bundle.title.value | escape }}</h3>
      {%- if bundle.badge_label.value != blank -%}
        <span class="cx__badge">{{ bundle.badge_label.value | escape }}</span>
      {%- endif -%}

      {%- comment -%} Il risparmio, così come questo bundle lo esprime {%- endcomment -%}
      {%- if dv.kind == 'percentage' -%}
        <p>Risparmia {{ dv.bps | divided_by: 100 }}%</p>
      {%- elsif dv.kind == 'fixed_amount' -%}
        <p>Risparmia {{ dv.amount | times: rate | money }}</p>
      {%- endif -%}

      {%- case type -%}
        {%- comment -%} un blocco per tipo — qui vanno le sezioni da 23.2 a 23.7 {%- endcomment -%}
      {%- endcase -%}
    </article>
  {%- endfor -%}
{%- endif -%}

23.2 Bundle fisso

Elenchi i figli con role == 'component' usando la catena di fallback del nome, mostri il prezzo del bundle quando il bundle usa la modalità prezzo (config.price, unità minori), e colleghi al prodotto padre acquistabile:

{%- when 'fixed' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'component' -%}
        {%- liquid
          assign name = c.label.value
          if name == blank
            assign name = c.variant.value.title
          endif
          if name == blank or name == 'Default Title'
            assign name = c.variant.value.product.title
          endif
        -%}
        {%- if name != blank -%}
          <li>{{ c.quantity.value }}× {{ name | escape }}</li>
        {%- endif -%}
      {%- endif -%}
    {%- endfor -%}
  </ul>
  {%- if cfg.price -%}
    <p class="cx__price">{{ cfg.price | times: rate | money }}</p>
  {%- endif -%}
  {%- if bundle.product.value != blank -%}
    <a href="{{ bundle.product.value.url }}">Acquista questo bundle</a>
  {%- endif -%}

Un bundle fisso in modalità prezzo porta config.price e nessun discount_value; in modalità sconto è il contrario — la riga del risparmio dello scheletro copre già il secondo caso.

In un prodotto con una sola variante il titolo della variante è il segnaposto di Shopify «Default Title»: la catena di fallback lo salta e usa il titolo del prodotto (a questo serve la condizione aggiuntiva).

23.3 Sconto per volume

La scala vive in tiers (ordinati per position), ogni fascia con i propri min_qty e discount_value:

{%- when 'volume' -%}
  <table>
    {%- for t in bundle.tiers.value -%}
      {%- assign tv = t.discount_value.value -%}
      <tr>
        <td>Compra {{ t.min_qty.value }}+</td>
        <td>
          {%- if tv.kind == 'percentage' -%}
            {{ tv.bps | divided_by: 100 }}% di sconto
          {%- else -%}
            {{ tv.amount | times: rate | money }} di sconto
          {%- endif -%}
        </td>
      </tr>
    {%- endfor -%}
  </table>

23.4 Compra X ricevi Y

La regola è due scalari in config; una percentuale del 100% (bps == 10000) significa che gli articoli premio sono gratis:

{%- when 'bogo' -%}
  <p>Compra {{ cfg.buy_qty }}, ricevi {{ cfg.get_qty }}
    {%- if dv.kind == 'percentage' and dv.bps == 10000 %} gratis{% else %} scontati{% endif -%}.</p>

23.5 Mix & match e componi la scatola

Entrambe sono offerte del tipo "raggiungi una quantità": il mix legge il min_items del metaobject, la scatola legge config.slots (e config.box_price quando la scatola addebita un prezzo chiuso). Il gruppo idoneo è in config.eligible (vedi 22.4):

{%- when 'mix_and_match' -%}
  <p>Scegli {{ bundle.min_items.value }} o più dalla selezione.</p>
{%- when 'build_a_box' -%}
  <p>Componi una scatola da {{ cfg.slots }}.
    {%- if cfg.box_price %} Prezzo della scatola {{ cfg.box_price | times: rate | money }}.{% endif -%}</p>

23.6 Complementi (FBT)

I componenti portano ruoli: l'anchor è il prodotto principale, i figli suggestion sono i complementi:

{%- when 'fbt' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'suggestion' or c.role.value == 'anchor' -%}
        <li>
          {{ c.variant.value.product.title | default: c.label.value | escape }}
          {%- if c.role.value == 'anchor' %} <em>(questo articolo)</em>{% endif -%}
        </li>
      {%- endif -%}
    {%- endfor -%}
  </ul>

23.7 Combo

Un combo annida sotto-offerte. Raggruppi i suoi figli per position diviso 1000 (ogni sotto-offerta occupa una fascia di 1000) o percorra config.of[] — mai raggruppare per role, che si ripete tra le sotto-offerte:

{%- when 'combo' -%}
  <ol>
    {%- for sub in cfg.of -%}
      <li>{{ sub.type | replace: '_', ' ' }}</li>
    {%- endfor -%}
  </ol>

23.8 Offerte regalo per l'intero negozio, su qualsiasi pagina

I regali pubblicizzati su ogni pagina prodotto vivono su un metafield del negozio, e il Liquid del tema non risolve un elenco di metaobject a livello negozio (22.1). Legga invece il JSON index e risolva ogni bundle per handle:

{%- assign index = shop.metafields.combora.index.value -%}
{%- if index != blank -%}
  {%- for entry in index.bundles -%}
    {%- if entry.all_pdp and entry.status == 'active' -%}
      {%- assign gift = metaobjects['combora_bundle'][entry.handle] -%}
      {%- if gift != blank -%}
        <aside class="cx__gift">
          <strong>{{ gift.title.value | escape }}</strong>
          {%- assign gcfg = gift.config.value -%}
          {%- if gcfg.threshold -%}
            <span>Spendi {{ gcfg.threshold | times: rate | money }} per sbloccarlo.</span>
          {%- endif -%}
        </aside>
      {%- endif -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}

23.9 Lo snippet completo

Tutto quanto sopra assemblato in un unico file funzionante — lo scheletro, i sei corpi per tipo, i regali per l'intero negozio e un CSS minimo perché sia leggibile fin da subito: scarichi combora-custom-bundle.liquid. Lo salvi come snippets/combora-custom-bundle.liquid nel Suo tema e lo renderizzi dal template di prodotto con {% render 'combora-custom-bundle', product: product %}. Il GWP non è nel case di proposito: un regalo viene pubblicizzato (23.8 o i blocchi propri dell'app) e aggiunto automaticamente dall'app — non c'è nulla che un widget di scheda prodotto debba vendere.

24Cronologia di questa edizione

Ogni flusso in questo manuale è stato testato in un negozio reale. Ecco la traccia di quando è stato verificato e cosa è cambiato in seguito, così sa quanto è aggiornato ciò che sta leggendo.

Gli screenshot si trovano in app/combora/public/manual/img/ nel repository: quelli dell'interfaccia dell'app sotto img/<language>/, un set per lingua, e quelli del negozio online e dell'admin Shopify nella radice, perché questi seguono il Suo tema e il Suo admin anziché la lingua dell'app. Vengono ripresi dal negozio demo; vedi docs/manual/CAPTURAS.md per lo stato richiesto per ciascuno.