Storefront SDK

The Storefront SDK is a small JavaScript library that the JeriCommerce app adds to your Shopify theme. It gives your own pages the same loyalty data and actions the Loyalty Hub uses: the customer's points, tier and progress, rewards, discount codes, ways to earn, points history and wallet card.

You write the HTML, the styles and the layout. The SDK takes care of the rest: it signs the customer in through Shopify, calls the JeriCommerce API, caches what you read, refreshes your data after every action and tells your page when something changes.

When to use the SDK ¶

• You want a loyalty page with your own design, beyond what the Loyalty Hub settings allow.
• You want to show loyalty data in other places of your theme, such as the header, the cart or a product page.
• You want to open the JeriCommerce widget from your own buttons, or hide its launcher on some pages.

Set it up ¶

Quick start ¶

<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() downloads the SDK the first time you call it and always resolves with the same instance. It does not load any data until you call a method.

How sign-in works ¶

The SDK always acts for the customer signed in to your Shopify store. There are only two states:

• Visitor: auth.getSession() resolves with { authenticated: false }. Public data works (program, tiers, public rewards, ways to earn, public boosts). customer.get() and customer.getTierProgress() resolve with null. The methods marked Customer in the reference reject with the authentication_required error code.
• Signed-in customer: { authenticated: true }. Everything works for that customer.

The SDK never accepts a token, an email or a customer id, so a page can never read or change another customer's data. To ask a visitor to sign in, call jeri.auth.login(). It sends them to the Shopify login and back to the current page, or to the page you pass as returnTo.

What happens after an action ¶

When a customer claims a reward, completes a way to earn, or updates their profile:

1. The promise resolves with the result of that action right away, for example the discount code of a claimed reward. Show it immediately.
2. The SDK marks the affected data as out of date, so the next read never returns the data from before the action.
3. In the background, it reads again the data your page already loaded and fires the matching events, such as customer:updated with the new balance.

Your page never needs to call refresh() after an action. Subscribe to the events you display and render them again when they fire. The points history, the referral link and the wallet links have no event. To keep the history up to date, call history.list() again when customer:updated fires.

Methods ¶

Every method returns a promise. Methods marked Customer need a signed-in customer and reject with authentication_required for visitors. Methods marked Public work for everyone.

When you leave out page and limit, the API uses its own defaults.

Data you can render ¶

All results are the objects of the JeriCommerce API, unchanged. These are the fields you will use most.

Update preferences ¶

customer.updatePreferences() needs every notification flag, plus language if you want to change it:

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

Requests always use the language of the page. Saving a language preference refreshes the customer's data but does not change the language of the page.

Events ¶

jeri.on(event, callback) returns a function that removes the subscription. Events also fire the first time your page reads that data, and on() doesn't send the last value again. Render what each read resolves with, as in the quick start, and use the events for later changes.

Events only report data changes. The result of an action is the value its promise resolves with.

Errors ¶

Every failed call rejects with a StorefrontSdkError. Check its code, not the message text:

The widget and the SDK ¶

The SDK can control the Storefront Widget on the current page: jeri.widget.open(), close(), showLauncher() and hideLauncher(). These calls only affect the page view; the saved widget settings do not change. When the widget is turned off in JeriCommerce, widget.open() rejects with widget_unavailable and everything else keeps working.

Widget pages ¶

widget.open({ page }) accepts these pages:

Visitors always see the program benefits and sign-up page.

Limitations ¶

• The SDK is only available on Shopify storefronts through the app embed. There is no npm package.
• Shopify's Canvas theme editor does not support app embeds yet, so the SDK is not available on Canvas themes.
• The SDK does not create accounts or sign customers up. Visitors sign in through Shopify.
• Points are never calculated in the browser. If the API still returns the previous balance, that is the latest data until the next read.

Examples ¶

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