Storefront SDK

Le Storefront SDK est une petite bibliothèque JavaScript que l’application JeriCommerce ajoute à votre thème Shopify. Elle donne à vos propres pages les mêmes données et actions de fidélité que le Loyalty Hub : les points du client, son niveau et sa progression, les récompenses, les codes de réduction, les moyens de gagner des points, l’historique des points et la carte wallet.

Vous écrivez le HTML, les styles et la mise en page. Le SDK s’occupe du reste : il connecte le client via Shopify, appelle l’API JeriCommerce, met en cache ce que vous lisez, actualise vos données après chaque action et prévient votre page quand quelque chose change.

Quand utiliser le SDK ¶

• Vous voulez une page de fidélité avec votre propre design, au-delà de ce que permettent les réglages du Loyalty Hub.
• Vous voulez afficher des données de fidélité à d’autres endroits de votre thème, comme l’en-tête, le panier ou une page produit.
• Vous voulez ouvrir le widget JeriCommerce depuis vos propres boutons, ou masquer son lanceur sur certaines pages.

Mise en place ¶

Démarrage rapide ¶

<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() télécharge le SDK au premier appel et renvoie toujours la même instance. Il ne charge aucune donnée tant que vous n’appelez pas une méthode.

Comment fonctionne la connexion ¶

Le SDK agit toujours pour le client connecté à votre boutique Shopify. Il n’y a que deux états :

• Visiteur : auth.getSession() renvoie { authenticated: false }. Les données publiques fonctionnent (programme, niveaux, récompenses publiques, moyens de gagner des points, boosts publics). customer.get() et customer.getTierProgress() renvoient null. Les méthodes marquées Customer dans la référence sont rejetées avec le code d’erreur authentication_required.
• Client connecté : { authenticated: true }. Tout fonctionne pour ce client.

Le SDK n’accepte jamais de jeton, d’e-mail ni d’identifiant client : une page ne peut donc jamais lire ni modifier les données d’un autre client. Pour demander à un visiteur de se connecter, appelez jeri.auth.login(). Il est envoyé vers la connexion Shopify puis ramené à la page actuelle, ou à la page que vous passez dans returnTo.

Ce qui se passe après une action ¶

Quand un client réclame une récompense, termine un moyen de gagner des points ou met à jour son profil :

1. La promesse se résout tout de suite avec le résultat de l’action, par exemple le code de réduction d’une récompense réclamée. Affichez-le immédiatement.
2. Le SDK marque les données concernées comme périmées, pour que la lecture suivante ne renvoie jamais les données d’avant l’action.
3. En arrière-plan, il relit les données que votre page avait déjà chargées et déclenche les événements correspondants, comme customer:updated avec le nouveau solde.

Votre page n’a jamais besoin d’appeler refresh() après une action. Abonnez-vous aux événements que vous affichez et refaites le rendu quand ils se déclenchent. L’historique des points, le lien de parrainage et les liens du wallet n’ont pas d’événement. Pour garder l’historique à jour, appelez à nouveau history.list() quand customer:updated se déclenche.

Méthodes ¶

Chaque méthode renvoie une promesse. Les méthodes marquées Customer nécessitent un client connecté et sont rejetées avec authentication_required pour les visiteurs. Les méthodes marquées Public fonctionnent pour tout le monde.

Si vous omettez page et limit, l’API utilise ses propres valeurs par défaut.

Données à afficher ¶

Tous les résultats sont les objets de l’API JeriCommerce, tels quels. Voici les champs que vous utiliserez le plus.

Mettre à jour les préférences ¶

customer.updatePreferences() nécessite tous les indicateurs de notification, plus language si vous voulez la changer :

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,
});

Les requêtes utilisent toujours la langue de la page. Enregistrer une préférence de langue actualise les données du client mais ne change pas la langue de la page.

Événements ¶

jeri.on(event, callback) renvoie une fonction qui supprime l’abonnement. Les événements se déclenchent aussi la première fois que votre page lit ces données, et on() ne renvoie pas la dernière valeur. Affichez ce que renvoie chaque lecture, comme dans le démarrage rapide, et utilisez les événements pour les changements suivants.

Les événements signalent uniquement des changements de données. Le résultat d’une action est la valeur avec laquelle sa promesse se résout.

Erreurs ¶

Chaque appel en échec est rejeté avec une StorefrontSdkError. Vérifiez son code, pas le texte du message :

Le widget et le SDK ¶

Le SDK peut contrôler le widget Storefront sur la page actuelle : jeri.widget.open(), close(), showLauncher() et hideLauncher(). Ces appels n’affectent que l’affichage de la page ; les réglages enregistrés du widget ne changent pas. Quand le widget est désactivé dans JeriCommerce, widget.open() est rejeté avec widget_unavailable et tout le reste continue de fonctionner.

Pages du widget ¶

widget.open({ page }) accepte ces pages :

Les visiteurs voient toujours la page des avantages du programme et d’inscription.

Limites ¶

• Le SDK n’est disponible que sur les boutiques Shopify, via l’app embed. Il n’existe pas de package npm.
• L’éditeur de thème Canvas de Shopify ne prend pas encore en charge les app embeds : le SDK n’est donc pas disponible sur les thèmes Canvas.
• Le SDK ne crée pas de comptes et n’inscrit pas les clients. Les visiteurs se connectent via Shopify.
• Les points ne sont jamais calculés dans le navigateur. Si l’API renvoie encore l’ancien solde, c’est la dernière donnée disponible jusqu’à la prochaine lecture.

Exemples ¶

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