Storefront SDK

El Storefront SDK es una pequeña librería de JavaScript que la aplicación JeriCommerce añade a tu tema de Shopify. Da a tus propias páginas los mismos datos y acciones de fidelización que usa el Loyalty Hub: los puntos del cliente, su nivel y su progreso, las recompensas, los códigos de descuento, las formas de ganar puntos, el historial de puntos y la tarjeta de Wallet.

Tú escribes el HTML, los estilos y el diseño. El SDK se encarga del resto: inicia la sesión del cliente a través de Shopify, llama a la API de JeriCommerce, guarda en caché lo que lees, actualiza tus datos después de cada acción y avisa a tu página cuando algo cambia.

Cuándo usar el SDK ¶

• Quieres una página de fidelización con tu propio diseño, más allá de lo que permiten los ajustes del Loyalty Hub.
• Quieres mostrar datos de fidelización en otros lugares de tu tema, como la cabecera, el carrito o una página de producto.
• Quieres abrir el widget de JeriCommerce desde tus propios botones, o ocultar su botón flotante en algunas páginas.

Configúralo ¶

Inicio rápido ¶

<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() descarga el SDK la primera vez que lo llamas y siempre devuelve la misma instancia. No carga ningún dato hasta que llamas a un método.

Cómo funciona el inicio de sesión ¶

El SDK siempre actúa en nombre del cliente que ha iniciado sesión en tu tienda Shopify. Solo hay dos estados:

• Visitante: auth.getSession() devuelve { authenticated: false }. Los datos públicos funcionan (programa, niveles, recompensas públicas, formas de ganar puntos, boosts públicos). customer.get() y customer.getTierProgress() devuelven null. Los métodos marcados como Customer en la referencia se rechazan con el código de error authentication_required.
• Cliente con sesión iniciada: { authenticated: true }. Todo funciona para ese cliente.

El SDK nunca acepta un token, un email ni un id de cliente, así que una página nunca puede leer ni modificar los datos de otro cliente. Para pedir a un visitante que inicie sesión, llama a jeri.auth.login(). Lo envía al inicio de sesión de Shopify y de vuelta a la página actual, o a la página que pases como returnTo.

Qué ocurre después de una acción ¶

Cuando un cliente reclama una recompensa, completa una forma de ganar puntos o actualiza su perfil:

1. La promesa se resuelve de inmediato con el resultado de esa acción, por ejemplo el código de descuento de una recompensa reclamada. Muéstralo al instante.
2. El SDK marca los datos afectados como desactualizados, de modo que la siguiente lectura nunca devuelve los datos de antes de la acción.
3. En segundo plano, vuelve a leer los datos que tu página ya había cargado y lanza los eventos correspondientes, como customer:updated con el nuevo saldo.

Tu página nunca necesita llamar a refresh() después de una acción. Suscríbete a los eventos que muestras y vuelve a renderizarlos cuando se lancen. El historial de puntos, el enlace de referido y los enlaces del wallet no tienen evento. Para mantener el historial al día, vuelve a llamar a history.list() cuando se lance customer:updated.

Métodos ¶

Todos los métodos devuelven una promesa. Los métodos marcados como Customer necesitan un cliente con sesión iniciada y se rechazan con authentication_required para los visitantes. Los métodos marcados como Public funcionan para todos.

Si omites page y limit, la API usa sus propios valores por defecto.

Datos que puedes mostrar ¶

Todos los resultados son los objetos de la API de JeriCommerce, sin modificar. Estos son los campos que más usarás.

Actualizar preferencias ¶

customer.updatePreferences() necesita todos los indicadores de notificación, además de language si quieres cambiarlo:

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

Las solicitudes siempre usan el idioma de la página. Guardar una preferencia de idioma actualiza los datos del cliente, pero no cambia el idioma de la página.

Eventos ¶

jeri.on(event, callback) devuelve una función que elimina la suscripción. Los eventos también se lanzan la primera vez que tu página lee esos datos, y on() no vuelve a enviar el último valor. Renderiza lo que devuelve cada lectura, como en el inicio rápido, y usa los eventos para los cambios posteriores.

Los eventos solo informan de cambios en los datos. El resultado de una acción es el valor con el que se resuelve su promesa.

Errores ¶

Toda llamada fallida se rechaza con un StorefrontSdkError. Comprueba su code, no el texto del mensaje:

El widget y el SDK ¶

El SDK puede controlar el widget de la tienda en la página actual: jeri.widget.open(), close(), showLauncher() y hideLauncher(). Estas llamadas solo afectan a la vista de la página; los ajustes guardados del widget no cambian. Cuando el widget está desactivado en JeriCommerce, widget.open() se rechaza con widget_unavailable y todo lo demás sigue funcionando.

Páginas del widget ¶

widget.open({ page }) acepta estas páginas:

Los visitantes siempre ven la página de beneficios del programa y de registro.

Limitaciones ¶

• El SDK solo está disponible en tiendas Shopify a través del app embed. No hay paquete de npm.
• El editor de temas Canvas de Shopify aún no admite app embeds, así que el SDK no está disponible en temas Canvas.
• El SDK no crea cuentas ni registra clientes. Los visitantes inician sesión a través de Shopify.
• Los puntos nunca se calculan en el navegador. Si la API todavía devuelve el saldo anterior, ese es el dato más reciente hasta la siguiente lectura.

Ejemplos ¶

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