Loyalty Page: modelli CDN personalizzati

Per i merchant che vogliono controllare completamente il layout HTML o creare una pagina loyalty personalizzata, JeriCommerce mette a disposizione modelli di sezione Liquid standalone che caricano il motore della loyalty page direttamente dal CDN.

Vuoi saltare la configurazione manuale? La skill AI loyalty-template-creator può generare un modello .liquid personalizzato completo, in linea con lo stile visivo del negozio. Fornisci un URL di riferimento: analizzerà colori, font, layout e risorse per creare un modello pronto all’uso basato sullo stesso motore CDN descritto di seguito.

Installala con: npx skills add jericommerce/skills --skill loyalty-template-creator

Source: github.com/JeriCommerce/skills

Quando usare la modalità CDN ¶

• Il merchant vuole un layout completamente personalizzato, oltre le possibilità offerte dalle impostazioni dell’editor del tema.
• Il team di sviluppo preferisce gestire direttamente l’HTML nel codice del tema.
• Vuoi integrare la loyalty page in un modello di pagina esistente insieme ad altre sezioni.

Procedura di configurazione ¶

{
  "sections": {
    "loyalty": {
      "type": "jeri-loyalty"
    }
  },
  "order": ["loyalty"]
}

Come funziona la modalità CDN ¶

I modelli CDN caricano lo stesso JavaScript che alimenta il blocco dell’estensione app del tema: è raggruppato, minificato e sempre aggiornato:

<!-- Always the latest version -->
<script src="https://cdn.jericommerce.com/shopify/loyalty-page.js" defer></script>
<link rel="stylesheet" href="https://cdn.jericommerce.com/shopify/loyalty-page.css" />

Il motore rileva automaticamente il dominio del negozio dall’attributo data-shop dell’elemento radice oppure usa window.Shopify.shop come alternativa.

Sistema dei modelli: associazione dei dati ¶

Il motore dei modelli usa due sistemi per associare i dati API all’HTML.

1. Interpolazione delle variabili — {varName} ¶

Inserisci token {varName} in qualsiasi punto del testo HTML. Il motore JS scorre tutti i nodi di testo e li sostituisce con i dati API.

<h3>{tier.name}</h3>
<span>{tier.requiredPoints}</span>
<span>{earning.points}</span>

Nei modelli ripetuti (livelli, accumuli), le variabili fanno riferimento ai dati del modello. La sintassi usa parentesi graffe singole {key} e non entra in conflitto con Liquid ({{ }}), i template literal JS (${ }) o CSS.

Sono disponibili anche variabili globali (come {programName} e {currencySymbol}), utilizzabili in qualsiasi nodo di testo del modello, non solo in quelli ripetuti. Consulta la sezione Variabili globali del modello per l’elenco completo.

2. Attributi dei dati — data-jeri ¶

Si usano per operazioni non testuali che non si possono esprimere tramite interpolazione del testo:

Riferimento rapido: quale usare ¶

Variabili globali del modello ¶

Puoi usare queste 7 variabili globali in qualsiasi nodo di testo dentro #jeri-loyalty-page-root. Scrivile con la sintassi {variableName}: il motore le sostituisce automaticamente con i dati della configurazione del programma.

Esempio d’uso ¶

<h1>Welcome to {programName}!</h1>
<p>Earn {balanceName} with every {currencySymbol} you spend</p>
<p>Prices are in {currencyCode}</p>

Le variabili globali funzionano insieme a quelle con ambito limitato ({earning.*}, {tier.*}). Nei modelli ripetuti vengono risolte entrambe.

La variabile {currencySymbol} usa Intl.NumberFormat del browser per determinare il simbolo corretto in base al codice valuta del programma. Il simbolo si adatta quindi alla valuta effettiva: $ per USD, € per EUR, £ per GBP e così via.

Campi dati disponibili ¶

Campi di accumulo (earning.*) ¶

Da usare nel modello <template data-jeri="earning-row">.

Campi dei livelli (tier.*) ¶

Da usare nel modello <template data-jeri="tiers">.

Elemento radice obbligatorio ¶

Ogni modello personalizzato deve includere questo elemento radice con gli attributi richiesti:

<div
  id="jeri-loyalty-page-root"
  class="jeri-loyalty-page jeri-loyalty-page--loading"
  data-shop="{{ shop.permanent_domain }}"
  data-icon-base="https://cdn.jericommerce.com/shopify/"
  data-locale="{{ request.locale.iso_code }}"
>
  <!-- Your custom HTML here -->
</div>

La classe jeri-loyalty-page--loading mostra uno scheletro e nasconde i contenuti finché i dati non vengono caricati. JS la rimuove dopo aver recuperato i dati.

Regole dei modelli ¶

Le 6 regole per i modelli personalizzati:

1. Mantieni id="jeri-loyalty-page-root" sull’elemento radice: serve a JS per inizializzarsi.
2. Mantieni class="jeri-loyalty-page" sull’elemento radice: qui sono definite le variabili CSS.
3. Mantieni data-shop: è obbligatorio per le chiamate API.
4. Mantieni le coppie modello/contenitore: a <template data-jeri="X"> deve corrispondere un <div data-jeri="X"> fratello.
5. Usa {varName} nei nodi di testo: il motore sostituisce tutti i token riconosciuti.
6. Usa data-jeri-html="key" per i contenuti HTML, non {var}, che verrebbe sottoposto a escape.

Struttura del modello predefinito ¶

Sezione hero ¶

<section class="jeri-loyalty-page__hero">
  <h1 class="jeri-loyalty-page__hero-title">Our Loyalty Program</h1>
  <p class="jeri-loyalty-page__hero-subtitle">Join our loyalty program...</p>

  <!-- CTA adapts to login state via Liquid -->
  <div class="jeri-loyalty-page__hero-cta">
    {% if customer %}
      {% if block.settings.cta_action == 'widget_rewards' %}
        <a href="#jeri=loyalty/rewards" class="jeri-loyalty-page__cta-button jeri-loyalty-page__cta-button--primary">
          {{ block.settings.logged_in_cta_label | default: 'See rewards' }}
        </a>
      {% else %}
        <a href="{{ block.settings.logged_in_cta_url | default: '/account' }}" class="jeri-loyalty-page__cta-button jeri-loyalty-page__cta-button--primary">
          {{ block.settings.logged_in_cta_label | default: 'See rewards' }}
        </a>
      {% endif %}
    {% else %}
      <a href="{{ block.settings.guest_cta_url | default: '/account/login' }}" class="jeri-loyalty-page__cta-button jeri-loyalty-page__cta-button--primary">
        {{ 'loyalty_page.hero_cta' | t }}
      </a>
    {% endif %}
  </div>
</section>

Sezione livelli ¶

<template data-jeri="tiers">
  <div class="jeri-tier-card">
    <div class="jeri-tier-card__body">
      <div class="jeri-tier-card__top">
        <h3 class="jeri-tier-card__name">{tier.name}</h3>
        <span class="jeri-tier-card__factor" data-jeri="tier.factor" data-jeri-hide-if="1">
          {tier.factor}x
        </span>
      </div>
      <div class="jeri-tier-card__meta">
        <span class="jeri-tier-card__points">{tier.requiredPoints}</span>
      </div>
      <p class="jeri-tier-card__content" data-jeri-html="tier.content"></p>
    </div>
  </div>
</template>

<!-- Container: cloned cards are appended here -->
<div data-jeri="tiers" class="jeri-tier-grid"></div>

Sezione accumuli ¶

<!-- Purchase earnings group -->
<div class="jeri-earning-group" data-jeri-group="purchases">
  <h3 class="jeri-earning-group__title">Purchases</h3>
  <div class="jeri-earning-list" data-jeri="earnings-purchases"></div>
</div>

<!-- Action earnings group -->
<div class="jeri-earning-group" data-jeri-group="actions">
  <h3 class="jeri-earning-group__title">Actions</h3>
  <div class="jeri-earning-list" data-jeri="earnings-actions"></div>
</div>

<!-- Shared template for both groups -->
<template data-jeri="earning-row">
  <div class="jeri-earning-row">
    <img class="jeri-earning-row__icon" data-jeri="earning.iconUrl" alt="" width="48" height="48" loading="lazy" />
    <div class="jeri-earning-row__content">
      <h3 class="jeri-earning-row__title">{earning.title}</h3>
      <p class="jeri-earning-row__description">{earning.description}</p>
    </div>
    <span class="jeri-earning-row__points">{earning.points}</span>
  </div>
</template>

Esempio completo di modello personalizzato ¶

Ecco un modello personalizzato minimal completo da usare come punto di partenza:

<!-- CDN Scripts -->
<script src="https://cdn.jericommerce.com/shopify/loyalty-page.js" defer></script>
<link rel="stylesheet" href="https://cdn.jericommerce.com/shopify/loyalty-page.css" />

<div
  id="jeri-loyalty-page-root"
  class="jeri-loyalty-page jeri-loyalty-page--loading"
  data-shop="{{ shop.permanent_domain }}"
  data-icon-base="https://cdn.jericommerce.com/shopify/"
  data-locale="{{ request.locale.iso_code }}"
>

  <!-- Hero -->
  <section class="jeri-loyalty-page__hero">
    <h1 class="jeri-loyalty-page__hero-title">Our Loyalty Program</h1>
    <p class="jeri-loyalty-page__hero-subtitle">Join and start earning rewards today.</p>
    <div class="jeri-loyalty-page__hero-cta">
      {% if customer %}
        <a href="/account" class="jeri-loyalty-page__cta-button jeri-loyalty-page__cta-button--primary">
          See rewards
        </a>
      {% else %}
        <a href="/account/login" class="jeri-loyalty-page__cta-button jeri-loyalty-page__cta-button--primary">
          Join now
        </a>
      {% endif %}
    </div>
  </section>

  <!-- Tiers -->
  <template data-jeri="tiers">
    <div>
      <h3>{tier.name}</h3>
      <p>{tier.requiredPoints}</p>
      <span data-jeri="tier.factor" data-jeri-hide-if="1">
        Factor: {tier.factor}x
      </span>
      <div data-jeri-html="tier.content"></div>
    </div>
  </template>
  <div data-jeri="tiers"></div>

  <!-- Earnings -->
  <template data-jeri="earning-row">
    <div>
      <img data-jeri="earning.iconUrl" alt="" width="32" height="32" />
      <strong>{earning.title}</strong>
      <span>{earning.points}</span>
      <p>{earning.description}</p>
    </div>
  </template>
  <div data-jeri-group="purchases">
    <h3>Purchases</h3>
    <div data-jeri="earnings-purchases"></div>
  </div>
  <div data-jeri-group="actions">
    <h3>Actions</h3>
    <div data-jeri="earnings-actions"></div>
  </div>

  <!-- Loading skeleton -->
  <div class="jeri-loyalty-page__skeleton">
    <div class="jeri-loyalty-page__skeleton-hero"></div>
  </div>

</div>

Modello visuale e modello minimal ¶

Modello visuale — Ideale per i brand che vogliono una loyalty page curata, in stile marketing, con sezione hero, passaggi esplicativi, righe di accumulo con icone SVG, schede dei livelli e scheletro di caricamento completo.

Modello minimal — Ideale per i negozi che preferiscono un approccio essenziale e basato sui dati, con elenchi compatti, CSS inline e senza dipendenze da fogli di stile esterni oltre al motore JS.

Entrambi i modelli usano lo stesso motore JS e lo stesso sistema di associazione dei dati. Cambiano solo la struttura HTML e il design visivo. Puoi partire da uno dei due e personalizzarlo liberamente.

Sistema delle icone ¶

Le icone delle righe di accumulo sono file SVG denominati in base al tipo. L’URL viene composto come data-icon-base + nome + .svg.

In modalità CDN, l’URL di base delle icone è fisso: https://cdn.jericommerce.com/shopify/. Se manca data-icon-base o un’icona non esiste, l’elemento <img> viene nascosto automaticamente.

Formato di visualizzazione dei punti ¶

Il campo earning.points usa un formato compatto in base al tipo di accumulo:

Per i referral, il badge mostra solo i punti di chi invita. Il premio dell’amico è indicato nella descrizione.

La descrizione dell’accumulo per acquisto usa dinamicamente il simbolo di valuta effettivo del programma (ad es. "Earn x3 Points per $ spent" per USD, "Earn x3 Points per € spent" per EUR). La valuta viene ricavata dalla configurazione del programma usando Intl.NumberFormat del browser.

Risoluzione dei nomi Wallet ¶

La configurazione del programma determina quattro proprietà dei nomi:

Vengono lette da program.configurations.wallet (configurazione di base). Il singolare o il plurale viene scelto automaticamente in base alla quantità (1 = singolare, altrimenti plurale).

Questi quattro nomi sono disponibili anche come variabili globali del modello: {balanceName}, {singularBalanceName}, {tierBalanceName} e {singularTierBalanceName}. Puoi richiamarli direttamente in qualsiasi nodo di testo.

Impostazioni dell’editor del tema ¶

Integrazione del widget ¶

La CTA "See rewards" (quando cta_action è impostato su widget_rewards) usa #jeri=loyalty/rewards come href. Se il widget JeriCommerce è attivo nella pagina, facendo clic sul link si apre il pannello premi. Quindi:

• La loyalty page spiega il programma con informazioni pubbliche.
• Il widget gestisce premi, transazioni e account con autenticazione.
• Funzionano indipendentemente, ma si completano tramite il formato URL #jeri=.

Visibilità condizionale ¶

La pagina nasconde automaticamente gli elementi in base alla configurazione del programma:

Variabili CSS ¶

Variabili visibili al merchant ¶

Il modello Liquid le imposta su :root in base ai colori scelti nell’editor del tema:

Variabili interne ¶

Risolvono i valori del merchant e aggiungono token strutturali e di layout. Sovrascrivili in Custom CSS per un controllo più preciso:

Esempio: modifica la spaziatura ¶

.jeri-loyalty-page {
  --jlp-space: 12px;
  --jlp-border-radius: 8px;
}

Esempio: tema scuro ¶

.jeri-loyalty-page {
  --jlp-card-bg: #1a1a1a;
  --jlp-border-color: #333;
  --jlp-divider: #2a2a2a;
  --jlp-skeleton-bg: #222;
}

Riferimento alle classi CSS ¶

Layout ¶

Hero ¶

Come funziona ¶

Accumuli ¶

Livelli ¶

Internazionalizzazione (i18n) ¶

La loyalty page supporta più lingue in base alla lingua attuale del negozio:

• Inglese (en), predefinito
• Spagnolo (es)
• Francese (fr)
• Tedesco (de)
• Italiano (it)

Le lingue non supportate ripiegano automaticamente sull’inglese.

Come funziona ¶

L'internazionalizzazione si articola su due livelli:

• Testi Liquid (renderizzati lato server) — Usano il filtro Shopify {{ 'key' | t }} con i file JSON delle lingue in locales/. Traducono testi statici come "Purchases", "Actions", i passaggi "How It Works" e il pulsante CTA per gli ospiti.
• Testi TypeScript (renderizzati lato client) — Usano l'utilità condivisa i18n.ts con file .ts delle lingue inclusi nel bundle JS. Traducono titoli e descrizioni dinamici dei flussi di accumulo.

Rilevamento della lingua ¶

La lingua del negozio viene passata a JavaScript tramite l'attributo data-locale dell'elemento radice:

<div id="jeri-loyalty-page-root" data-locale="{{ request.locale.iso_code }}" ...>
</div>

Aggiungere una nuova lingua ¶

1. Crea theme-extensions/loyalty-page/locales/{lang}.ts (copia en.ts e traduci i testi)
2. Crea theme-extensions/loyalty-page/locales/{lang}.json (copia en.default.json e traduci i testi)
3. Importa la nuova lingua in loyalty-page.ts e aggiungila a initFromSession(locale, { en, es, fr, de, it, {lang} })
4. Esegui npm run build:theme-extensions per ricompilare

File di traduzione ¶