Loyalty-Seite: Benutzerdefinierte CDN-Vorlagen

Für Händler, die das HTML-Layout vollständig kontrollieren oder eine komplett eigene Loyalty-Seite erstellen möchten, stellt JeriCommerce eigenständige Liquid-Abschnittsvorlagen bereit. Sie laden die Loyalty-Page-Engine direkt vom CDN.

Möchten Sie die manuelle Einrichtung überspringen? Der KI-Skill loyalty-template-creator kann eine vollständige benutzerdefinierte .liquid-Vorlage erstellen, die zum visuellen Stil Ihres Shops passt. Geben Sie eine Referenz-URL an. Der Skill analysiert Farben, Schriftarten, Layout und Medien und erstellt eine sofort nutzbare Vorlage auf Basis derselben CDN-Engine, die weiter unten beschrieben wird.

Installieren Sie ihn mit: npx skills add jericommerce/skills --skill loyalty-template-creator

Quelle: github.com/JeriCommerce/skills

Wann Sie den CDN-Modus verwenden sollten ¶

• Der Händler benötigt ein vollständig individuelles Layout, das über die Möglichkeiten der Theme-Editor-Einstellungen hinausgeht.
• Das Entwicklungsteam möchte das HTML direkt im Theme-Code verwalten.
• Sie müssen die Loyalty-Seite zusammen mit anderen Abschnitten in eine vorhandene Seitenvorlage integrieren.

Einrichtungsschritte ¶

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

Funktionsweise des CDN-Modus ¶

CDN-Vorlagen laden dasselbe JavaScript, das auch den Block der Theme-App-Erweiterung antreibt. Es ist gebündelt, minimiert und immer aktuell:

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

Die Engine erkennt die Shop-Domain automatisch anhand des Attributs data-shop am Wurzelelement. Andernfalls verwendet sie window.Shopify.shop.

Vorlagensystem: So funktioniert die Datenbindung ¶

Die Vorlagen-Engine verwendet zwei Verfahren, um API-Daten an Ihr HTML zu binden.

1. Variablenersetzung: {varName} ¶

Schreiben Sie {varName}-Platzhalter an beliebiger Stelle in Ihren HTML-Text. Die JS-Engine durchsucht alle Textknoten und ersetzt sie durch API-Daten.

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

In wiederholten Vorlagen (Stufen, Verdienste) beziehen sich Variablen auf die jeweiligen Vorlagendaten. Die Syntax mit einzelnen geschweiften Klammern {key} steht nicht in Konflikt mit Liquid ({{ }}), JS-Template-Literalen (${ }) oder CSS.

Außerdem gibt es globale Variablen wie {programName} und {currencySymbol}, die in jedem Textknoten der gesamten Vorlage funktionieren, auch außerhalb wiederholter Vorlagen. Die vollständige Liste finden Sie weiter unten im Abschnitt Globale Vorlagenvariablen.

2. Datenattribute: data-jeri ¶

Für Vorgänge ohne Text, die sich nicht durch Textersetzung abbilden lassen:

Kurzübersicht: Welches Verfahren wann? ¶

Globale Vorlagenvariablen ¶

Diese sieben globalen Variablen können in jedem Textknoten innerhalb von #jeri-loyalty-page-root verwendet werden. Schreiben Sie sie in der Form {variableName}. Die Engine ersetzt sie automatisch durch Werte aus der Programmeinstellung.

Anwendungsbeispiel ¶

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

Globale Variablen funktionieren zusammen mit bereichsgebundenen Variablen ({earning.*}, {tier.*}). In wiederholten Vorlagen werden beide Arten aufgelöst.

Die Variable {currencySymbol} verwendet Intl.NumberFormat des Browsers, um das passende Symbol zum Währungscode des Programms zu ermitteln. Das Symbol richtet sich also nach der tatsächlichen Programmwährung, etwa $ für USD, € für EUR oder £ für GBP.

Verfügbare Datenfelder ¶

Felder für Verdienste (earning.*) ¶

Wird innerhalb der Vorlage <template data-jeri="earning-row"> verwendet.

Felder für Stufen (tier.*) ¶

Wird innerhalb der Vorlage <template data-jeri="tiers"> verwendet.

Erforderliches Wurzelelement ¶

Jede benutzerdefinierte Vorlage muss dieses Wurzelelement mit den erforderlichen Attributen enthalten:

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

Die Klasse jeri-loyalty-page--loading zeigt ein Ladegerüst und blendet den Inhalt aus, bis die Daten geladen sind. Nach dem Abruf entfernt JavaScript die Klasse.

Vorlagenregeln ¶

Beachten Sie diese sechs Regeln für benutzerdefinierte Vorlagen:

1. Lassen Sie id="jeri-loyalty-page-root" am Wurzelelement stehen. JavaScript benötigt es zur Initialisierung.
2. Lassen Sie class="jeri-loyalty-page" am Wurzelelement stehen. Hier werden die CSS-Variablen definiert.
3. Lassen Sie data-shop stehen. Das Attribut ist für API-Aufrufe erforderlich.
4. Lassen Sie Vorlagen- und Container-Paare bestehen. Zu <template data-jeri="X"> gehört ein entsprechendes benachbartes <div data-jeri="X">.
5. Verwenden Sie {varName} in beliebigen Textknoten. Die Engine ersetzt alle erkannten Platzhalter.
6. Verwenden Sie data-jeri-html="key" für HTML-Inhalte. {var} würde als Text maskiert.

Struktur der Standardvorlage ¶

Hero-Bereich ¶

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

Stufenbereich ¶

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

Verdienstbereich ¶

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

Vollständiges Beispiel einer benutzerdefinierten Vorlage ¶

Hier sehen Sie eine vollständige, minimale benutzerdefinierte Vorlage als Ausgangspunkt:

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

Visuelle und minimale Vorlage ¶

Visuelle Vorlage: Ideal für Marken, die eine ausgearbeitete Loyalty-Seite im Marketingstil mit Hero-Bereich, Schritten zur Funktionsweise, Verdienstzeilen mit SVG-Symbolen, Stufenkarten und vollständigem Ladegerüst wünschen.

Minimale Vorlage: Ideal für Shops, die ein klares, datenorientiertes Layout mit kompakter Liste und Inline-CSS wünschen. Abgesehen von der JS-Engine ist kein externes Stylesheet erforderlich.

Beide Vorlagen verwenden dieselbe JS-Engine und dasselbe Datenbindungssystem. Sie unterscheiden sich nur in HTML-Struktur und visueller Gestaltung. Sie können mit jeder der beiden Vorlagen beginnen und sie frei anpassen.

Symbolsystem ¶

Die Symbole der Verdienstzeilen sind SVG-Dateien, deren Namen dem jeweiligen Typ entsprechen. Die Symbol-URL wird aus data-icon-base + Name + .svg gebildet.

Im CDN-Modus ist die Basis-URL der Symbole fest auf https://cdn.jericommerce.com/shopify/ gesetzt. Fehlt data-icon-base oder ist ein Symbol nicht vorhanden, wird das <img>-Element automatisch ausgeblendet.

Anzeigeformat für Punkte ¶

Das Feld earning.points verwendet je nach Verdienstart ein kompaktes Format:

Bei Empfehlungen zeigt das Badge nur die Punkte der werbenden Person. Die Prämie der eingeladenen Person steht im Beschreibungstext.

Die Beschreibung für Kaufverdienste verwendet dynamisch das tatsächliche Währungssymbol des Programms (z. B. "Earn x3 Points per $ spent" für USD oder "Earn x3 Points per € spent" für EUR). Die Währung wird anhand der Programmeinstellung mit Intl.NumberFormat des Browsers ermittelt.

Ermittlung der Wallet-Bezeichnungen ¶

Vier Bezeichnungseigenschaften werden aus der Programmeinstellung übernommen:

Diese Werte werden aus program.configurations.wallet (Basiskonfiguration) gelesen. Die Einzahl oder Mehrzahl wird automatisch anhand der Menge gewählt (1 = Einzahl, sonst Mehrzahl).

Diese vier Bezeichnungen sind auch als globale Vorlagenvariablen verfügbar: {balanceName}, {singularBalanceName}, {tierBalanceName} und {singularTierBalanceName}. Sie können sie direkt in jedem Textknoten verwenden.

Einstellungen im Theme-Editor ¶

Widget-Integration ¶

Der CTA "See rewards" verwendet cta_action, wenn widget_rewards auf #jeri=loyalty/rewards gesetzt ist. Ist das JeriCommerce-Widget auf der Seite aktiv, öffnet ein Klick auf diesen Link dessen Prämienbereich. Das bedeutet:

• Die Loyalty-Seite erklärt das Programm (öffentliche Informationen)
• Das Widget verwaltet Prämien, Transaktionen und Konten (nach der Anmeldung)
• Beide funktionieren unabhängig voneinander und ergänzen sich über das URL-Muster #jeri=

Bedingte Sichtbarkeit ¶

Die Seite blendet Elemente abhängig von der Programmeinstellung automatisch aus:

CSS-Variablen ¶

Variablen für Händler ¶

Die Liquid-Vorlage setzt diese Werte auf :root, basierend auf den Farbeinstellungen im Theme-Editor:

Interne Variablen ¶

Diese Variablen übernehmen die Händlerwerte und ergänzen Layout- und Strukturwerte. Überschreiben Sie sie bei Bedarf im Custom CSS, um Details anzupassen:

Beispiel: Abstände überschreiben ¶

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

Beispiel: Dunkles Theme ¶

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

Referenz der CSS-Klassen ¶

Layout ¶

Hero-Bereich ¶

Funktionsweise ¶

Verdienste ¶

Stufen ¶

Internationalisierung (i18n) ¶

Die Loyalty-Seite unterstützt abhängig von der aktuellen Spracheinstellung des Shops mehrere Sprachen:

• Englisch (en), Standard
• Spanisch (es)
• Französisch (fr)
• Deutsch (de)
• Italienisch (it)

Bei nicht unterstützten Spracheinstellungen wird automatisch Englisch verwendet.

Funktionsweise ¶

Die Internationalisierung umfasst zwei Ebenen:

• Liquid-Texte (serverseitig gerendert): Verwenden den Shopify-Filter {{ 'key' | t }} mit JSON-Dateien in locales/. Damit werden statische Texte wie "Purchases", "Actions", Schritte unter "How It Works" und der CTA-Button für Gäste übersetzt.
• TypeScript-Texte (clientseitig gerendert): Verwenden das gemeinsame Hilfsprogramm i18n.ts mit Sprachdateien im Format .ts, die in das JS gebündelt werden. Damit werden dynamische Titel und Beschreibungen von Verdienstabläufen übersetzt.

Erkennung der Spracheinstellung ¶

Die Spracheinstellung des Shops wird JavaScript über das Attribut data-locale am Wurzelelement übergeben:

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

Sprache hinzufügen ¶

1. Erstellen Sie theme-extensions/loyalty-page/locales/{lang}.ts (kopieren Sie en.ts und übersetzen Sie die Inhalte).
2. Erstellen Sie theme-extensions/loyalty-page/locales/{lang}.json (kopieren Sie en.default.json und übersetzen Sie die Inhalte).
3. Importieren Sie die neue Sprache in loyalty-page.ts und ergänzen Sie sie in initFromSession(locale, { en, es, fr, de, it, {lang} }).
4. Führen Sie zum erneuten Erstellen npm run build:theme-extensions aus.

Übersetzungsdateien ¶