Storefront SDK

Lo Storefront SDK è una piccola libreria JavaScript che l'app JeriCommerce aggiunge al tuo tema Shopify. Dà alle tue pagine gli stessi dati e le stesse azioni che usa la Loyalty Hub: punti, livello e avanzamento del cliente, premi, codici sconto, modi per guadagnare, cronologia punti e carta wallet.

Tu scrivi HTML, stili e layout. Al resto pensa l'SDK: fa accedere il cliente tramite Shopify, chiama l'API di JeriCommerce, mette in cache ciò che leggi, aggiorna i dati dopo ogni azione e avvisa la pagina quando qualcosa cambia.

Quando usare l'SDK ¶

• Vuoi una pagina fedeltà con un design tutto tuo, oltre quello che permettono le impostazioni della Loyalty Hub.
• Vuoi mostrare i dati fedeltà in altri punti del tema, come l'header, il carrello o una pagina prodotto.
• Vuoi aprire il widget JeriCommerce dai tuoi pulsanti, oppure nascondere il suo launcher in alcune pagine.

Configurazione ¶

Avvio rapido ¶

<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() scarica l'SDK la prima volta che lo chiami e restituisce sempre la stessa istanza. Non carica alcun dato finché non chiami un metodo.

Come funziona l'accesso ¶

L'SDK agisce sempre per conto del cliente che ha effettuato l'accesso al tuo negozio Shopify. Gli stati sono solo due:

• Visitatore: auth.getSession() restituisce { authenticated: false }. I dati pubblici funzionano (programma, livelli, premi pubblici, modi per guadagnare, boost pubblici). customer.get() e customer.getTierProgress() restituiscono null. I metodi indicati come Customer nella reference vengono rifiutati con il codice di errore authentication_required.
• Cliente connesso: { authenticated: true }. Tutto funziona per quel cliente.

L'SDK non accetta mai un token, un'email o un id cliente, quindi una pagina non può mai leggere o modificare i dati di un altro cliente. Per chiedere a un visitatore di accedere, chiama jeri.auth.login(). Lo porta al login di Shopify e poi di nuovo alla pagina corrente, oppure alla pagina che passi come returnTo.

Cosa succede dopo un'azione ¶

Quando un cliente riscatta un premio, completa un modo per guadagnare o aggiorna il profilo:

1. La promise si risolve subito con il risultato di quell'azione, ad esempio il codice sconto di un premio riscattato. Mostralo immediatamente.
2. L'SDK segna come non aggiornati i dati coinvolti, così la lettura successiva non restituisce mai i dati precedenti all'azione.
3. In background rilegge i dati che la tua pagina aveva già caricato e invia gli eventi corrispondenti, come customer:updated con il nuovo saldo.

La tua pagina non ha mai bisogno di chiamare refresh() dopo un'azione. Iscriviti agli eventi che mostri e renderizza di nuovo quando vengono emessi. Lo storico dei punti, il link di referral e i link del wallet non hanno un evento. Per tenere aggiornato lo storico, chiama di nuovo history.list() quando viene emesso customer:updated.

Metodi ¶

Ogni metodo restituisce una promise. I metodi contrassegnati come Customer richiedono un cliente connesso e vengono rifiutati con authentication_required per i visitatori. I metodi contrassegnati come Public funzionano per tutti.

Se ometti page e limit, l'API usa i propri valori predefiniti.

Dati che puoi mostrare ¶

Tutti i risultati sono gli oggetti dell'API di JeriCommerce, invariati. Questi sono i campi che userai più spesso.

Aggiornare le preferenze ¶

customer.updatePreferences() richiede tutti i flag di notifica, più language se vuoi cambiarla:

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

Le richieste usano sempre la lingua della pagina. Salvare una preferenza di lingua aggiorna i dati del cliente ma non cambia la lingua della pagina.

Eventi ¶

jeri.on(event, callback) restituisce una funzione che rimuove l'iscrizione. Gli eventi vengono emessi anche la prima volta che la pagina legge quei dati, e on() non reinvia l'ultimo valore. Renderizza quello che restituisce ogni lettura, come nell'avvio rapido, e usa gli eventi per le modifiche successive.

Gli eventi segnalano solo le modifiche ai dati. Il risultato di un'azione è il valore con cui si risolve la sua promise.

Errori ¶

Ogni chiamata fallita viene rifiutata con uno StorefrontSdkError. Controlla il suo code, non il testo del messaggio:

Il widget e l'SDK ¶

L'SDK può controllare il widget storefront nella pagina corrente: jeri.widget.open(), close(), showLauncher() e hideLauncher(). Queste chiamate influiscono solo sulla visualizzazione della pagina; le impostazioni salvate del widget non cambiano. Quando il widget è disattivato in JeriCommerce, widget.open() viene rifiutato con widget_unavailable e tutto il resto continua a funzionare.

Pagine del widget ¶

widget.open({ page }) accetta queste pagine:

I visitatori vedono sempre la pagina dei vantaggi del programma e dell'iscrizione.

Limitazioni ¶

• L'SDK è disponibile solo negli storefront Shopify tramite l'app embed. Non esiste un pacchetto npm.
• L'editor di temi Canvas di Shopify non supporta ancora gli app embed, quindi l'SDK non è disponibile nei temi Canvas.
• L'SDK non crea account e non iscrive i clienti. I visitatori accedono tramite Shopify.
• I punti non vengono mai calcolati nel browser. Se l'API restituisce ancora il saldo precedente, quello è il dato più recente fino alla lettura successiva.

Esempi ¶

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