Page de fidélité : modèles CDN personnalisés

Pour les marchands qui souhaitent maîtriser toute la structure HTML ou créer une page de fidélité entièrement personnalisée, JeriCommerce propose des modèles de section Liquid autonomes qui chargent le moteur de la page de fidélité directement depuis le CDN.

Vous souhaitez éviter la configuration manuelle ? La skill IA loyalty-template-creator peut générer un modèle .liquid complet et personnalisé qui reprend le style visuel de votre boutique. Fournissez-lui une URL de référence : elle analyse les couleurs, les polices, la mise en page et les ressources pour produire un modèle prêt à l’emploi, basé sur le même moteur CDN que celui décrit ci-dessous.

Installez-la avec : npx skills add jericommerce/skills --skill loyalty-template-creator

Source : github.com/JeriCommerce/skills

Quand utiliser le mode CDN ¶

• Le marchand souhaite une mise en page entièrement personnalisée, au-delà des possibilités offertes par les paramètres de l’éditeur de thème.
• L’équipe de développement préfère gérer directement le HTML dans le code du thème.
• Vous devez intégrer la page de fidélité à un modèle de page existant, aux côtés d’autres sections.

Étapes de configuration ¶

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

Fonctionnement du mode CDN ¶

Les modèles CDN chargent le même JavaScript que le bloc d’extension d’application de thème, regroupé, minifié et toujours à jour :

<!-- 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" />

Le moteur détecte automatiquement le domaine de la boutique depuis l’attribut data-shop de l’élément racine, ou utilise window.Shopify.shop en dernier recours.

Système de modèles : liaison des données ¶

Le moteur de modèles utilise deux systèmes pour relier les données de l’API à votre HTML.

1. Interpolation de variables : {varName} ¶

Insérez des expressions {varName} n’importe où dans le contenu textuel de votre HTML. Le moteur JS parcourt tous les nœuds textuels et les remplace par les données de l’API.

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

Dans les modèles répétitifs (niveaux, gains), les variables sont limitées aux données du modèle. La syntaxe utilise des accolades simples {key}, sans conflit avec Liquid ({{ }}), les littéraux de gabarit JS (${ }) ou le CSS.

Des variables globales (comme {programName} et {currencySymbol}) fonctionnent aussi dans tous les nœuds textuels du modèle, y compris en dehors des modèles répétitifs. Consultez la section Variables globales du modèle ci-dessous pour obtenir la liste complète.

2. Attributs de données : data-jeri ¶

Ils servent aux opérations non textuelles qui ne peuvent pas être exprimées par interpolation :

Référence rapide : quelle syntaxe utiliser ¶

Variables globales du modèle ¶

Ces 7 variables globales peuvent être utilisées dans n’importe quel nœud textuel à l’intérieur de #jeri-loyalty-page-root. Écrivez-les avec la syntaxe {variableName} : le moteur les remplace automatiquement par les données de configuration du programme.

Exemple d’utilisation ¶

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

Les variables globales fonctionnent avec les variables limitées au modèle ({earning.*}, {tier.*}). Dans les modèles répétitifs, les deux types de variables sont résolus.

La variable {currencySymbol} utilise la fonction native Intl.NumberFormat du navigateur pour déterminer le symbole correspondant au code de devise du programme. Le symbole s’adapte donc à la devise réelle du programme : $ pour USD, € pour EUR, £ pour GBP, etc.

Champs de données disponibles ¶

Champs des gains (earning.*) ¶

À utiliser dans le modèle <template data-jeri="earning-row">.

Champs des niveaux (tier.*) ¶

À utiliser dans le modèle <template data-jeri="tiers">.

Élément racine obligatoire ¶

Chaque modèle personnalisé doit inclure cet élément racine avec les attributs requis :

<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 affiche un squelette de chargement et masque le contenu jusqu’au chargement des données. Le JS la supprime une fois les données récupérées.

Règles des modèles ¶

Les 6 règles à respecter pour les modèles personnalisés :

1. Conservez id="jeri-loyalty-page-root" sur l’élément racine : le JS en a besoin pour s’initialiser.
2. Conservez class="jeri-loyalty-page" sur la racine : les variables CSS y sont définies.
3. Conservez data-shop, indispensable aux appels API.
4. Conservez les paires modèle/conteneur : un <template data-jeri="X"> doit avoir un <div data-jeri="X"> correspondant au même niveau.
5. Utilisez librement {varName} dans les nœuds textuels : le moteur remplace toutes les expressions qu’il reconnaît.
6. Utilisez data-jeri-html="key" pour le contenu HTML (et non {var}, dont les caractères seraient échappés).

Structure du modèle par défaut ¶

Section d’accueil ¶

<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>

Section des niveaux ¶

<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>

Section des gains ¶

<!-- 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>

Exemple complet de modèle personnalisé ¶

Voici un modèle personnalisé minimal complet à utiliser comme point de départ :

<!-- 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>

Modèle visuel ou minimal ¶

Modèle visuel : adapté aux marques qui souhaitent une page de fidélité soignée, orientée marketing, avec une section d’accueil, des étapes expliquant le fonctionnement, des lignes de gains avec icônes SVG, des cartes de niveaux et un squelette de chargement complet.

Modèle minimal : adapté aux boutiques qui préfèrent une présentation épurée centrée sur les données, avec une liste compacte, du CSS intégré et aucune dépendance à une feuille de style externe, en complément du moteur JS.

Les deux modèles utilisent le même moteur JS et le même système de liaison des données. Seules la structure HTML et la présentation visuelle diffèrent. Vous pouvez partir de l’un ou de l’autre et le personnaliser librement.

Système d’icônes ¶

Les icônes des lignes de gains sont des fichiers SVG nommés selon leur type. L’URL d’une icône est calculée ainsi : data-icon-base + nom + .svg.

En mode CDN, l’URL de base des icônes est définie dans le code sur https://cdn.jericommerce.com/shopify/. Si data-icon-base est absent ou si une icône n’existe pas, l’élément <img> est automatiquement masqué.

Format d’affichage des points ¶

Le champ earning.points utilise un format compact selon le type de gain :

Pour le parrainage, seuls les points du parrain figurent dans le badge. La récompense de l’ami est mentionnée dans la description.

La description des gains liés aux achats utilise dynamiquement le symbole de la devise réelle du programme (par exemple, « Gagnez x3 points par $ dépensé » pour USD, ou « Gagnez x3 points par € dépensé » pour EUR). La devise est déterminée à partir de la configuration du programme avec Intl.NumberFormat du navigateur.

Résolution des noms du Wallet ¶

Quatre propriétés de nommage sont récupérées dans la configuration du programme :

Ces propriétés sont lues depuis program.configurations.wallet (configuration de base). Le singulier ou le pluriel est appliqué automatiquement selon le montant (1 = singulier, sinon pluriel).

Ces quatre noms sont également disponibles comme variables globales du modèle : {balanceName}, {singularBalanceName}, {tierBalanceName} et {singularTierBalanceName}. Vous pouvez donc les utiliser directement dans n’importe quel nœud textuel.

Paramètres de l’éditeur de thème ¶

Intégration du widget ¶

Le bouton d’action "See rewards" (lorsque cta_action vaut widget_rewards) utilise #jeri=loyalty/rewards comme cible de lien. Si le widget JeriCommerce est actif sur la page, un clic sur ce lien ouvre son panneau de récompenses. Ainsi :

• La page de fidélité explique le programme (informations publiques).
• Le widget gère les récompenses, les transactions et le compte (après authentification).
• Les deux fonctionnent indépendamment, mais se complètent grâce au format d’URL #jeri=.

Visibilité conditionnelle ¶

La page masque automatiquement certains éléments selon la configuration du programme :

Variables CSS ¶

Variables configurables par le marchand ¶

Le modèle Liquid définit ces variables sur :root à partir des paramètres de couleur de l’éditeur de thème :

Variables internes ¶

Ces variables reprennent celles du marchand et ajoutent des valeurs pour la mise en page et la structure. Redéfinissez-les dans Custom CSS pour un contrôle plus précis :

Exemple : modifier les espacements ¶

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

Exemple : thème sombre ¶

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

Référence des classes CSS ¶

Mise en page ¶

Accueil ¶

Fonctionnement ¶

Gains ¶

Niveaux ¶

Internationalisation (i18n) ¶

La page de fidélité prend en charge plusieurs langues selon la langue actuelle de la boutique :

• Anglais (en), par défaut
• Espagnol (es)
• Français (fr)
• Allemand (de)
• Italien (it)

Les langues non prises en charge utilisent automatiquement l’anglais.

Fonctionnement ¶

L’internationalisation comporte deux couches :

• Textes côté Liquid (rendus sur le serveur) : utilisent le filtre Shopify {{ 'key' | t }} avec des fichiers JSON de langue dans locales/. Ils traduisent les textes statiques, comme « Purchases », « Actions », les étapes « How It Works » et le bouton d’action des visiteurs non connectés.
• Textes côté TypeScript (rendus dans le navigateur) : utilisent l’utilitaire partagé i18n.ts avec des fichiers .ts de langue inclus dans le JS. Ils traduisent les titres et descriptions dynamiques des flux de gains.

Détection de la langue ¶

La langue de la boutique est transmise au JavaScript via l’attribut data-locale de l’élément racine :

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

Ajouter une langue ¶

1. Créez theme-extensions/loyalty-page/locales/{lang}.ts (copiez en.ts et traduisez-le).
2. Créez theme-extensions/loyalty-page/locales/{lang}.json (copiez en.default.json et traduisez-le).
3. Importez la nouvelle langue dans loyalty-page.ts et ajoutez-la à initFromSession(locale, { en, es, fr, de, it, {lang} }).
4. Exécutez npm run build:theme-extensions pour reconstruire les fichiers.

Fichiers de traduction ¶