SDK: Componenti in pagina la guida completa

I Componenti in Pagina ti permettono di integrare elementi visivi e interattivi del tuo programma fedeltà (come la lista delle campagne, il catalogo ricompense o il profilo utente) direttamente all'interno delle pagine del tuo sito web o e-commerce, offrendo un'esperienza utente fluida e personalizzata.

Panoramica e Tipologie di Componenti

Accedendo alla sezione Componenti in Pagina, visualizzerai il listing principale suddiviso per categorie. Se non hai ancora creato componenti, ogni categoria mostrerà il box "Nessun componente creato per questa categoria" con un pulsante Aggiungi nuovo.

Le categorie a disposizione includono:

• Lista Campagne: Per mostrare ai clienti le campagne fedeltà attive e i relativi punti.
• Catalogo Ricompense: Per mostrare i premi riscattabili.
• Lista Attività: Per permettere all'utente di tracciare i propri movimenti (punti guadagnati, utilizzati, ricompense riscattate).
• Profilo Utente: Per visualizzare e gestire i dati del consumer.
• Lista Livelli VIP: Per mostrare i livelli del programma e la progressione dell'utente.
• Badge Punti Carrello / Prodotto: Widget specifici per mostrare i punti guadagnabili direttamente nella scheda prodotto o nel carrello.
• Iscrizione Referral: Form di iscrizione dedicato agli invitati tramite link referral.

1. Creazione e Configurazione Generale di un Componente

Per avviare la creazione, clicca su + Nuovo componente in alto a destra o su Aggiungi nuovo all'interno della categoria d'interesse.

La schermata di configurazione si divide in quattro tab principali, assistita da una Preview in tempo reale sulla destra dove si possono simulare diverse modalità:

Dispositivo utilizzato: Desktop, Tablet e Mobile

Stato utente: loggato o ospite

Lingua: in caso di multilingua si ha la possibilità di vedere il componente in diverse lingue

Tab 1: Generale

In questa prima scheda andrai a definire le informazioni di base e i comportamenti strutturali:

• Informazioni Base: Inserisci il Nome componente (obbligatorio) e una Descrizione interna per identificarlo. Imposta lo Stato su Pubblicato o Bozza.

  Email Consentite: Campo utile in fase di test. Puoi inserire indirizzi email specifici autorizzati a visualizzare i componenti anche quando sono ancora in stato di bozza.

  Link Pagine: Configura le mappature dei link dinamici del tuo sito inserendo le macro tra parentesi graffe:

  • Login: pagina dove avviene il login sul sito
  • Registrazione: pagina dove avviene la registrazione sul sito
  • Referral: pagina in cui è integrato il componente dedicato, dove i nuovi utenti possono registrarsi tramite la campagna invita un amico.

2. Componenti Globali

Nel tab Componenti Globali puoi allineare perfettamente alla brand identity del tuo sito web, componenti primitivi di base come Button (Bottoni) e Input (Campi di testo).

Configurazione del Bottone (Button)

• Sizes (SM, MD, LG, XL): Seleziona la taglia da configurare e imposta per ciascuna la Dimensione Font, il Padding orizzontale e il Padding verticale (espressi in pixel).

  Stile bordo: Scegli l'arrotondamento degli angoli (es. Smussato).

  Varianti (Solid, Outline, Ghost, Surface): Definisci l'aspetto grafico per le diverse varianti. Per ogni variante puoi mappare i colori dello stato Default e dello stato Hover:

  • Sfondo: (es. inserendo il codice esadecimale #1331B6     ).
  • Colore testo: (es. #FFFFFF     ).
• Stato disabilitato: Regola l'opacità del bottone quando non è cliccabile (tramite slider da 0 a 1).

Configurazione dei Campi di Testo (Input)

• Sizes (SM, MD, LG, XL): Definisci anche qui le dimensioni del font e i relativi padding verticali/orizzontali.
• Stile bordo & Varianti (Filled, Outline, Surface, Flushed): Scegli la resa visiva dei campi e configurala per gli stati di Default e Focus andando a impostare Sfondo e Colore testo.
• Placeholder & Stato disabilitato: Personalizza il colore del testo segnaposto (placeholder) e l'opacità del campo qualora fosse disabilitato.

3.Contenuto

Tab 3 — Contenuto

Il tab Contenuto è il cuore della personalizzazione visiva del componente. Da qui puoi configurare nel dettaglio ogni elemento dell'interfaccia che verrà mostrata all'utente finale.

Le opzioni disponibili variano a seconda del componente selezionato, ma la logica del pannello è la stessa per tutte le categorie.  Come funzionano i breakpoint, i campi colore, le varianti, si applicano in modo identico ovunque. Una volta capito come funziona un componente, sai usarli tutti. In alto trovi un menu a tendina Sezione che ti permette di navigare tra le diverse aree di configurazione. Le sezioni tipicamente presenti sono:

Layout: controlla la struttura della griglia (numero di colonne per riga) e la spaziatura tra gli elementi. I valori sono differenziabili per breakpoint (Desktop, Tablet, Mobile).

Sezione: configura il contenitore esterno del componente: colore di sfondo, allineamento dell'intestazione, testo e stile del titolo e del sottotitolo. I testi supportano la localizzazione per lingua e possono mostrare contenuti diversi a seconda che l'utente sia loggato o ospite.

Card: definisce l'aspetto visivo delle singole card: modalità di layout (impilato o in linea), variante grafica (Ghost, Solid, Outline, Surface), stile dei bordi, colori e ombra per stato normale e hover, icona, testi, badge, box punti, pulsante CTA e padding interno ed esterno.

Modale: configura il popup di dettaglio che si apre al click su una card: dimensione, stile bordo, allineamento, sfondo, icona, titolo, sottotitolo, descrizione e pulsanti di azione.

Badge: l'aspetto del badge informativo mostrato nel componente (es. nel carrello, per comunicare i punti guadagnabili con l'acquisto).

Sezioni specifiche per componente: a seconda del tipo di componente, possono essere presenti sezioni dedicate, ad esempio per la gestione di badge, stati dei livelli VIP, spaziatura ecc.

4. Avanzate

Mentre le sezioni precedenti permettono una configurazione visuale guidata, il tab Avanzate offre gli strumenti per una personalizzazione profonda del componente SDK.

CSS Personalizzato

Questa sezione include un editor di codice integrato che permette di sovrascrivere gli stili predefiniti del componente.

• Cosa puoi fare Se le opzioni nei "Componenti Globali" non sono sufficienti puoi scrivere qui le tue regole CSS.
• Vantaggio: Le regole inserite in questo campo avranno la priorità sugli stili base di Poinzilla, applicandosi esclusivamente a questo specifico componente.

Variabili CSS (Design Tokens)

Il sistema SDK di Poinzilla è costruito su una solida architettura di 222 Variabili CSS.

• Efficienza: invece di riscrivere intere classi, puoi modificare direttamente i "token" (es. --pz-primary-color      o --pz-card-border-radius     ).
• Consistenza: modificando una variabile alla radice, il cambiamento si rifletterà istantaneamente su tutti gli elementi correlati del componente, garantendo un'armonia visiva perfetta senza errori di targeting dei selettori.

truttura HTML

Espandendo questa sezione, avrai accesso alla mappatura della struttura del componente (DOM).

• Guida allo sviluppo: è essenziale per capire quali classi o ID utilizzare all'interno del campo "CSS Personalizzato". Ti permette di vedere come sono nidificati gli elementi (es. contenitore card, titolo, pulsante, saldo punti) per poterli puntare con precisione chirurgica.

5. Salvataggio e Integrazione nel Sito (Incopora)

Una volta completata la personalizzazione e verificata la resa visiva nella preview di destra, clicca sul pulsante verde Salva in alto.

Dopo il salvataggio, apparirà il tab Incorpora. All'interno di questa sezione troverai i codici necessari per visualizzare il componente sul tuo sito web. Ti basterà copiarli e incollarli nella posizione desiderata:

Integrazione dei componenti su Shopify

Se utilizzi Shopify, puoi integrare i componenti Poinzilla direttamente nel tema del tuo negozio, senza dover inserire manualmente codice o Web Component.

L'integrazione avviene in tre passaggi:

1. Attiva Poinzilla nel tema

Dalla sezione Componenti in pagina, clicca su Attiva Poinzilla nel tema.

L'integrazione è già predisposta: dopo aver cliccato il pulsante, vai su Salva in alto a destra.

Questa operazione va effettuata una sola volta per il tema.

2. Scegli quali componenti utilizzare

Dopo aver attivato Poinzilla nel tema, abilita l'opzione Abilita i componenti in pagina.

Per ogni componente puoi scegliere dal menu a tendina la versione che vuoi utilizzare.

Le versioni dei componenti vengono create e configurate dalla sezione Componenti in pagina del pannello Poinzilla. Qui puoi quindi decidere, ad esempio, quale versione del Badge Punti Prodotto o del Badge Punti Carrello utilizzare nel tuo negozio.

Una volta selezionate le versioni desiderate, clicca su Salva.

3. Inserisci i componenti nelle pagine del negozio

A questo punto puoi decidere dove mostrare i componenti utilizzando l'editor del tema Shopify.

Clicca su Apri l'editor del tema e raggiungi la pagina in cui vuoi inserire il componente.

Nel Theme Editor clicca su Aggiungi blocco e cerca il blocco Poinzilla corrispondente:

• Poinzilla Badge Prodotto → per mostrare i punti nella pagina prodotto;
• Poinzilla Badge Carrello → per mostrare i punti nella pagina del carrello;
• Poinzilla Componente → per inserire gli altri componenti Poinzilla, ad esempio campagne, premi, profilo utente o programma fedeltà.

Trascina il blocco nella posizione desiderata e clicca su Salva.

Altre piattaforme

Per integrare i componenti su altre piattaforme e-commerce o siti web personalizzati, utilizza i codici disponibili nella scheda Incorpora, che compare dopo il salvataggio del componente.

Shortcode WordPress

Se utilizzi WordPress, copia lo shortcode generato e incollalo nell'editor della pagina o del contenuto in cui vuoi visualizzare il componente.

Web Component HTML

Per piattaforme come PrestaShop o per siti web personalizzati, copia il tag HTML del Web Component e inseriscilo nel codice sorgente della pagina, nella posizione in cui desideri mostrare il componente.