Storefront SDK

Das Storefront SDK ist eine kleine JavaScript-Bibliothek, die die JeriCommerce-App zu deinem Shopify-Theme hinzufügt. Es gibt deinen eigenen Seiten dieselben Loyalty-Daten und Aktionen wie dem Loyalty Hub: Punkte, Stufe und Fortschritt des Kunden, Belohnungen, Rabattcodes, Sammelmöglichkeiten, Punkteverlauf und Wallet-Karte.

Du schreibst HTML, Styles und Layout. Den Rest übernimmt das SDK: Es meldet den Kunden über Shopify an, ruft die JeriCommerce-API auf, speichert gelesene Daten im Cache, aktualisiert deine Daten nach jeder Aktion und meldet deiner Seite, wenn sich etwas ändert.

Wann das SDK sinnvoll ist ¶

• Du möchtest eine Loyalty-Seite mit eigenem Design, die über die Einstellungen des Loyalty Hub hinausgeht.
• Du möchtest Loyalty-Daten an anderen Stellen deines Themes anzeigen, zum Beispiel im Header, im Warenkorb oder auf einer Produktseite.
• Du möchtest das JeriCommerce-Widget über eigene Buttons öffnen oder seinen Launcher auf manchen Seiten ausblenden.

Einrichten ¶

Schnellstart ¶

<div data-jeri-points>Loading your points...</div>

<script type="module">
  const box = document.querySelector("[data-jeri-points]");

  if (!window.JeriCommerce) {
    box.textContent = "Loyalty is not available right now.";
  } else {
    const jeri = await window.JeriCommerce.ready();
    const session = await jeri.auth.getSession();

    if (!session.authenticated) {
      box.innerHTML = '<button type="button">Sign in to see your points</button>';
      box.querySelector("button").addEventListener("click", () => jeri.auth.login());
    } else {
      const render = data => {
        box.textContent = `You have ${data?.customer.loyaltyData?.balance ?? 0} points`;
      };
      render(await jeri.customer.get());
      jeri.on("customer:updated", render);
    }
  }
</script>

JeriCommerce.ready() lädt das SDK beim ersten Aufruf herunter und liefert immer dieselbe Instanz zurück. Es lädt keine Daten, bevor du eine Methode aufrufst.

So funktioniert die Anmeldung ¶

Das SDK handelt immer für den Kunden, der in deinem Shopify-Shop angemeldet ist. Es gibt nur zwei Zustände:

• Besucher: auth.getSession() liefert { authenticated: false }. Öffentliche Daten funktionieren (Programm, Stufen, öffentliche Belohnungen, Sammelmöglichkeiten, öffentliche Boosts). customer.get() und customer.getTierProgress() liefern null. Die Methoden, die in der Referenz mit Customer markiert sind, werden mit dem Fehlercode authentication_required abgelehnt.
• Angemeldeter Kunde: { authenticated: true }. Alles funktioniert für diesen Kunden.

Das SDK akzeptiert nie ein Token, eine E-Mail-Adresse oder eine Kunden-ID, daher kann eine Seite nie die Daten eines anderen Kunden lesen oder ändern. Um einen Besucher zur Anmeldung aufzufordern, rufe jeri.auth.login() auf. Das leitet ihn zum Shopify-Login und danach zurück zur aktuellen Seite oder zu der Seite, die du als returnTo übergibst.

Was nach einer Aktion passiert ¶

Wenn ein Kunde eine Belohnung einlöst, eine Sammelmöglichkeit abschließt oder sein Profil aktualisiert:

1. Das Promise wird sofort mit dem Ergebnis dieser Aktion aufgelöst, zum Beispiel mit dem Rabattcode einer eingelösten Belohnung. Zeige ihn direkt an.
2. Das SDK markiert die betroffenen Daten als veraltet, damit der nächste Lesezugriff nie die Daten von vor der Aktion liefert.
3. Im Hintergrund liest es die Daten, die deine Seite bereits geladen hat, erneut und löst die passenden Events aus, zum Beispiel customer:updated mit dem neuen Kontostand.

Deine Seite muss nach einer Aktion nie refresh() aufrufen. Abonniere die Events der Daten, die du anzeigst, und rendere sie neu, wenn sie ausgelöst werden. Der Punkteverlauf, der Empfehlungslink und die Wallet-Links haben kein Event. Damit der Verlauf aktuell bleibt, rufe history.list() erneut auf, wenn customer:updated ausgelöst wird.

Methoden ¶

Jede Methode gibt ein Promise zurück. Methoden mit der Markierung Customer benötigen einen angemeldeten Kunden und werden für Besucher mit authentication_required abgelehnt. Methoden mit der Markierung Public funktionieren für alle.

Wenn du page und limit weglässt, verwendet die API ihre eigenen Standardwerte.

Daten, die du rendern kannst ¶

Alle Ergebnisse sind unveränderte Objekte der JeriCommerce-API. Dies sind die Felder, die du am häufigsten brauchst.

Einstellungen aktualisieren ¶

customer.updatePreferences() benötigt alle Benachrichtigungs-Flags, plus language, wenn du die Sprache ändern möchtest:

const data = await jeri.customer.get();
await jeri.customer.updatePreferences({
  balanceNotifications: data.customer.balanceNotifications,
  tierNotifications: data.customer.tierNotifications,
  locationNotifications: data.customer.locationNotifications,
  rewardAvailableNotifications: data.customer.rewardAvailableNotifications,
  marketingNotifications: true,
});

Anfragen verwenden immer die Sprache der Seite. Das Speichern einer Spracheinstellung aktualisiert die Daten des Kunden, ändert aber nicht die Sprache der Seite.

Events ¶

jeri.on(event, callback) gibt eine Funktion zurück, die das Abonnement entfernt. Events werden auch ausgelöst, wenn deine Seite diese Daten zum ersten Mal liest, und on() sendet den letzten Wert nicht erneut. Rendere das Ergebnis jeder Abfrage wie im Schnellstart und nutze die Events für spätere Änderungen.

Events melden nur Datenänderungen. Das Ergebnis einer Aktion ist der Wert, mit dem ihr Promise aufgelöst wird.

Fehler ¶

Jeder fehlgeschlagene Aufruf wird mit einem StorefrontSdkError abgelehnt. Prüfe seinen code, nicht den Meldungstext:

Das Widget und das SDK ¶

Das SDK kann das Storefront-Widget auf der aktuellen Seite steuern: jeri.widget.open(), close(), showLauncher() und hideLauncher(). Diese Aufrufe wirken nur auf die Seitenansicht; die gespeicherten Widget-Einstellungen ändern sich nicht. Wenn das Widget in JeriCommerce ausgeschaltet ist, wird widget.open() mit widget_unavailable abgelehnt, und alles andere funktioniert weiter.

Widget-Seiten ¶

widget.open({ page }) akzeptiert diese Seiten:

Besucher sehen immer die Programmvorteile und die Anmeldeseite.

Einschränkungen ¶

• Das SDK ist nur auf Shopify-Storefronts über das App-Embed verfügbar. Es gibt kein npm-Paket.
• Der Theme-Editor Canvas von Shopify unterstützt App-Embeds noch nicht, daher ist das SDK in Canvas-Themes nicht verfügbar.
• Das SDK erstellt keine Konten und registriert keine Kunden. Besucher melden sich über Shopify an.
• Punkte werden nie im Browser berechnet. Wenn die API noch den vorherigen Kontostand liefert, sind das die aktuellsten Daten bis zum nächsten Lesezugriff.

Beispiele ¶

try {
  const claimed = await jeri.rewards.claim({ rewardId: reward.id });
  showCode(claimed.code); // The balance updates through "customer:updated".
} catch (error) {
  if (error.code === "api_error" && error.serverCode === "NOT_ENOUGH_POINTS") {
    showMessage("You need more points for this reward.");
  } else {
    showMessage("Something went wrong. Please try again.");
  }
}

await jeri.rewards.claim({ rewardId: reward.id, pointsToRedeem: 200 });

const result = await jeri.earnings.execute({ earningId: earning.id, action: "flow" });
showMessage(`+${result.pointsAwarded} points`);

document.querySelector("[data-open-rewards]").addEventListener("click", () => {
  jeri.widget.open({ page: "rewards" }).catch(() => {
    window.location.href = "/pages/loyalty"; // The widget is turned off.
  });
});

const badge = document.querySelector("[data-points-badge]");
const show = data => {
  badge.hidden = !data;
  if (data) badge.textContent = data.customer.loyaltyData.balance;
};
show(await jeri.customer.get());
jeri.on("customer:updated", show);