Página de fidelización: plantillas CDN personalizadas

Para los comercios que necesitan controlar por completo el diseño HTML o crear una página de fidelización totalmente personalizada, JeriCommerce ofrece plantillas de sección Liquid independientes que cargan el motor de la página directamente desde el CDN.

¿Quiere omitir la configuración manual? La skill de IA loyalty-template-creator puede generar una plantilla .liquid personalizada completa que coincida con el estilo visual de su tienda. Proporcione una URL de referencia y analizará los colores, las fuentes, el diseño y los recursos para crear una plantilla lista para usar basada en el mismo motor CDN que se describe a continuación.

Instálela con: npx skills add jericommerce/skills --skill loyalty-template-creator

Fuente: github.com/JeriCommerce/skills

Cuándo usar el modo CDN ¶

Use el modo CDN cuando:

• El comerciante necesita un diseño totalmente personalizado que supere las opciones del editor del tema.
• El equipo de desarrollo prefiere gestionar el HTML directamente en el código del tema.
• La página de fidelización debe integrarse en una plantilla existente junto con otras secciones.

Pasos de configuración ¶

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

Cómo funciona el modo CDN ¶

Las plantillas CDN cargan el mismo JavaScript que impulsa el bloque de la extensión de la aplicación del tema. Está empaquetado, minificado y siempre actualizado:

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

El motor detecta automáticamente el dominio de la tienda mediante el atributo data-shop del elemento raíz. Si no está disponible, usa window.Shopify.shop.

Sistema de plantillas: cómo funciona la vinculación de datos ¶

El motor de plantillas ofrece dos métodos para vincular los datos de la API con el HTML.

1. Interpolación de variables: {varName} ¶

Escriba marcadores {varName} en cualquier parte del texto HTML. El motor JS recorre todos los nodos de texto y los sustituye por datos de la API.

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

En las plantillas repetidas (niveles y formas de obtener puntos), las variables corresponden a los datos de cada elemento. La sintaxis con una sola llave a cada lado, {key}, no entra en conflicto con Liquid ({{ }}), los literales de plantilla JS (${ }) ni CSS.

También hay variables globales, como {programName} y {currencySymbol}, que funcionan en cualquier nodo de texto de la plantilla, no solo en las plantillas repetidas. Consulte la lista completa en la sección Variables globales de plantilla.

2. Atributos de datos: data-jeri ¶

Se usan para operaciones que no son de texto y que no se pueden expresar mediante interpolación:

Referencia rápida: cuándo usar cada método ¶

Variables globales de plantilla ¶

Estas siete variables globales se pueden usar en cualquier nodo de texto dentro de #jeri-loyalty-page-root. Escríbalas con la sintaxis {variableName} y el motor las sustituirá automáticamente por los datos de configuración del programa.

Ejemplo de uso ¶

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

Las variables globales funcionan junto con las variables de ámbito ({earning.*}, {tier.*}). En las plantillas repetidas se resuelven ambos tipos.

La variable {currencySymbol} usa el Intl.NumberFormat nativo del navegador para determinar el símbolo adecuado según el código de moneda del programa. Así, el símbolo se adapta a la moneda real del programa: $ para USD, € para EUR, £ para GBP, etc.

Campos de datos disponibles ¶

Campos de formas de ganar (earning.*) ¶

Se usa dentro de la plantilla <template data-jeri="earning-row">.

Campos de nivel (tier.*) ¶

Se usa dentro de la plantilla <template data-jeri="tiers">.

Elemento raíz obligatorio ¶

Todas las plantillas personalizadas deben incluir este elemento raíz con los atributos obligatorios:

<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 clase jeri-loyalty-page--loading muestra una estructura de carga y oculta el contenido hasta que se cargan los datos. JavaScript la elimina después de obtenerlos.

Reglas de las plantillas ¶

Siga estas seis reglas para crear plantillas personalizadas:

1. Mantenga id="jeri-loyalty-page-root" en el elemento raíz. JavaScript lo necesita para inicializarse.
2. Mantenga class="jeri-loyalty-page" en el elemento raíz. Aquí se definen las variables CSS.
3. Mantenga el atributo data-shop. Es obligatorio para las llamadas a la API.
4. Mantenga los pares de plantilla y contenedor. Cada <template data-jeri="X"> necesita un <div data-jeri="X"> correspondiente como elemento hermano.
5. Use {varName} en cualquier nodo de texto. El motor sustituye todos los marcadores que reconoce.
6. Use data-jeri-html="key" para insertar contenido HTML. Con {var}, el contenido se escaparía como texto.

Estructura de la plantilla predeterminada ¶

Sección principal ¶

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

Sección de niveles ¶

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

Sección de formas de ganar ¶

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

Ejemplo completo de plantilla personalizada ¶

Aquí tiene una plantilla personalizada mínima y completa que puede usar como punto de partida:

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

Plantilla visual y minimalista ¶

Plantilla visual: ideal para marcas que buscan una página de fidelización cuidada y orientada al marketing, con una sección principal, pasos explicativos, filas para obtener puntos con iconos SVG, tarjetas de nivel y una estructura de carga completa.

Plantilla minimalista: ideal para tiendas que prefieren un enfoque claro y basado en datos, con una lista compacta y CSS integrado. No depende de hojas de estilos externas, aparte de la del motor JS.

Ambas plantillas usan el mismo motor JS y el mismo sistema de vinculación de datos. Solo cambia la estructura HTML y el diseño visual. Puede empezar con cualquiera y personalizarla libremente.

Sistema de iconos ¶

Los iconos de las filas para ganar puntos son archivos SVG cuyo nombre corresponde al tipo. La URL del icono se forma concatenando data-icon-base + nombre + .svg.

En el modo CDN, la URL base de los iconos está fijada en https://cdn.jericommerce.com/shopify/. Si falta data-icon-base o el icono no existe, el elemento <img> se oculta automáticamente.

Formato de visualización de puntos ¶

El campo earning.points usa un formato compacto según la forma de ganar puntos:

En las recomendaciones, la insignia solo muestra los puntos de quien recomienda. La recompensa de la persona invitada se indica en la descripción.

La descripción de los puntos por compra inserta dinámicamente el símbolo de moneda del programa. Por ejemplo, para USD puede mostrar «Gana x3 puntos por cada $ gastado» y para EUR, «Gana x3 puntos por cada € gastado». El navegador determina la moneda a partir de la configuración del programa mediante Intl.NumberFormat.

Resolución de los nombres de Wallet ¶

La configuración del programa proporciona cuatro propiedades de nombre:

Se obtienen de program.configurations.wallet (configuración base). La forma singular o plural se aplica automáticamente según la cantidad: 1 usa el singular y cualquier otro valor usa el plural.

Estos cuatro nombres también están disponibles como variables globales de plantilla: {balanceName}, {singularBalanceName}, {tierBalanceName} y {singularTierBalanceName}. Puede usarlas directamente en cualquier nodo de texto.

Ajustes del editor del tema ¶

Integración con el widget ¶

El CTA "See rewards", cuando cta_action tiene el valor widget_rewards, usa #jeri=loyalty/rewards como destino. Si el widget de JeriCommerce está activo en la página, al hacer clic en el enlace se abre su panel de recompensas. Esto significa que:

• La página de fidelización explica el programa y muestra información pública.
• El widget gestiona las recompensas, las transacciones y la cuenta de cada cliente con sesión iniciada.
• Ambos funcionan de forma independiente y se complementan mediante el patrón de URL #jeri=.

Visibilidad condicional ¶

La página oculta elementos automáticamente según la configuración del programa:

Variables CSS ¶

Variables para comerciantes ¶

La plantilla Liquid establece estos valores en :root según los ajustes de color del editor del tema:

Variables internas ¶

Estas resuelven las variables del comercio y añaden tokens estructurales y de diseño. Puede sobrescribirlas en Custom CSS para ajustar detalles específicos:

Ejemplo: cambiar el espaciado ¶

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

Ejemplo: tema oscuro ¶

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

Referencia de clases CSS ¶

Diseño ¶

Sección principal ¶

Cómo funciona ¶

Formas de ganar ¶

Niveles ¶

Internacionalización (i18n) ¶

La página de fidelización admite varios idiomas según el idioma actual de la tienda:

• Inglés (en), predeterminado
• Español (es)
• Francés (fr)
• Alemán (de)
• Italiano (it)

Los idiomas no compatibles usan inglés automáticamente.

Cómo funciona ¶

La internacionalización tiene dos capas:

• Textos de Liquid (renderizados en el servidor): usan el filtro de Shopify {{ 'key' | t }} con archivos JSON de idioma en locales/. Traducen texto estático como "Purchases", "Actions", los pasos de "How It Works" y el botón CTA para visitantes.
• Textos de TypeScript (renderizados en el cliente): usan la utilidad compartida i18n.ts y archivos de idioma .ts incluidos en el código JS. Traducen los títulos y las descripciones dinámicos de las formas de obtener puntos.

Detección del idioma ¶

El idioma de la tienda se pasa a JavaScript mediante el atributo data-locale del elemento raíz:

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

Añadir un idioma ¶

1. Cree theme-extensions/loyalty-page/locales/{lang}.ts (copie en.ts y traduzca su contenido)
2. Cree theme-extensions/loyalty-page/locales/{lang}.json (copie en.default.json y traduzca su contenido)
3. Importe el nuevo idioma en loyalty-page.ts y añádalo a initFromSession(locale, { en, es, fr, de, it, {lang} })
4. Ejecute npm run build:theme-extensions para volver a compilar

Archivos de traducción ¶