Integrare il ticketshop in modo nativo

Avvio rapido

Ci sono due modi per avere un negozio funzionante. Entrambi usano lo stesso script e lo stesso elemento; cambia chi crea la sessione.

Senza backend

L'elemento crea da solo una sessione del browser per la tua publicKey, limitata ai domini consentiti. Imposta cart-scope="tab": senza identità server, il valore predefinito "shared" termina con un errore esplicito. Ogni scheda del browser ha quindi il proprio carrello. La sessione è anonima: i visitatori navigano e riempiono il carrello. Prima della registrazione, element.config.onUserRequired deve restituire un token di sessione legato a un utente emesso da un server; senza di esso il negozio si ferma al carrello con un avviso.

<!-- Site without a backend: load the script once, place the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  cart-scope="tab"
></aditus-shop>

Con backend

Il tuo server crea la sessione con il mint secret e decide chi è l'acquirente. Passa il token restituito all'elemento. Con l'email dell'acquirente, il valore predefinito cart-scope "shared" mantiene un unico carrello in tutte le schede.

// 1. On your server: create a session. The mint secret never leaves the server.
const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
    "Content-Type": "application/json",
  },
  // email comes from your own login session, never from the browser request.
  body: JSON.stringify({ publicKey: "pk_your_site", email: user.email }),
});
const { sessionToken } = await res.json();

<!-- 2. In your page: pass the token from your server to the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  session-token="SESSION_TOKEN_FROM_YOUR_SERVER"
></aditus-shop>

Sostituisci pk_your_site con la tua chiave pubblicabile dall'admin ADITUS. developers.aditus.com è l'indirizzo di produzione per lo script e l'API. Entrambi i modi sono descritti in dettaglio più sotto.

La tecnologia dietro il micro-frontend

Il micro-frontend mostra l'intero processo d'acquisto (eventi, articoli, carrello, registrazione, pagamento, conclusione) nel DOM della tua pagina. Usa il layout della tua pagina e il tuo CSS può dare stile a ogni sua parte.

Il tuo sito è fidato: il tuo server autentica l'utente prima di creare una sessione identificata. Il micro-frontend viene mostrato deliberatamente nel Light DOM della tua pagina, senza isolamento iframe. Gli script della tua pagina possono accedere al DOM e allo storage del browser; proteggi quindi il tuo sito e gli script di terze parti. L'autorizzazione dell'origine tramite chiave pubblica non è un'autenticazione dell'utente. I dati di pagamento vengono inseriti solo sulla pagina esterna del fornitore di pagamento.

Sicurezza dei pagamenti, PCI e CSP

La preparazione dell'acquisto viene mostrata nella tua pagina. Il pagamento avviene sulla pagina del fornitore di pagamento, quindi nessun dato di pagamento passa dalla tua pagina.

Confronto con iframe e shadow DOM

Gli approcci a confronto

Alternativa: pacchetto sorgente (distribuzione autonoma)

In alternativa, scarica il pacchetto sorgente dalla tua istanza ADITUS e integralo nella tua app (Vite, webpack, Next.js o Nuxt). La distribuzione è a tuo carico: per ogni aggiornamento devi reinstallare, ricompilare e pubblicare. Non è su npm pubblico.

App SSR: Next.js e Nuxt

Il micro-frontend è volutamente solo client. Il suo contenuto è live e legato alla sessione: disponibilità, prezzi e carrello dell'utente esistono solo per una sessione autenticata al momento della richiesta, quindi non c'è nulla di significativo che il tuo server possa pre-renderizzare. mount() crea una nuova root React lato client (createRoot); Il markup rappresentato dal server all'interno del contenitore non è idratato. Ciò rende l'integrazione SSR semplice e prevedibile: esegui il rendering di un segnaposto sul server, montalo sul client e riserva lo spazio in modo che nulla salti.

// Next.js (App Router): the micro-frontend is deliberately client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@aditus/shop-embed";

export function TicketshopSection({ sessionToken }: { sessionToken: string }) {
  const el = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!el.current) return;
    const handle: ShopHandle = mount(el.current, {
      publicKey: "pk_your_site",
      sessionToken, // issued server-side, passed to the client component as a prop
      cartScope: "shared", // the default in frameworks too; trusted server identity
    });
    return () => handle(); // unmount on route change
  }, [sessionToken]);

  // Server and client render the SAME placeholder and so avoid a hydration mismatch.
  // min-height reserves the space so the page does not jump on mount (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

Il micro-frontend necessita di una sessione

import { mount } from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// Without a sessionToken the micro-frontend stays inactive: it only shows a
// neutral notice and starts no API calls: no cart, no registration,
// no checkout. Only a session activates the shop.
mount(el, {
  publicKey: "pk_your_site",
  // sessionToken missing -> the shop is not activated.
});

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

// getElementById can return null. Check it properly in TypeScript instead of using "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// AditusShopConfig types every option and gives you autocompletion.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",   // required as soon as a session is involved
  sessionToken,                // issued by your backend, keep it in memory only
  cartScope: "shared",          // default; requires a trusted server identity
};

const handle: ShopHandle = mount(el, config);

// The micro-frontend sends the X-Aditus-Session header with every shop call.
// On logout, revoke the session on the server and remount/update.

Al reload, un puntatore valido permette di richiedere il carrello server con lo stesso ambito autorizzato e identità fidata. Non è un'autorizzazione né una garanzia di ripristino dopo scadenza, cancellazione dello storage o cambio utente. tab non unisce i percorsi delle altre schede; shared mantiene il blocco checkout con un solo writer.

Il ritorno dal pagamento usa aditus-return (un token opaco, breve e legato al server) insieme ad aditus-pay. Può tornare nella stessa scheda o in una nuova, ma il server richiede client/origine autorizzati e identità fidata corrispondente. I parametri di ritorno non provano un acquisto. Il server verifica il pagamento e finalizza il tentativo legato al token; un esito sconosciuto resta bloccato per riconciliazione, senza ripetere alla cieca un nuovo acquisto. Ritorni scaduti o non autorizzati sono errori espliciti, non il permesso di creare un ordine sostitutivo.

Assegnare un fornitore prepara soltanto il pagamento: il riepilogo resta modificabile. Il blocco inizia al redirect effettivo, dopo i consensi richiesti. Un parametro di ritorno cancel/error non prova un fallimento: il backend ricontrolla il carrello; Completed con order.id conferma il completamento. Un nuovo tentativo richiede la rimozione riuscita e confermata dell'assegnazione per quello stesso carrello; gli esiti ambigui restano bloccati e possono essere ricontrollati. Questo non garantisce un rimborso né esclude una liquidazione tardiva.

Pagamento con reindirizzamento: cosa deve fare la tua pagina per la sessione

• Servi l'URL di ritorno configurato con l'embed montato. Preserva aditus-return e aditus-pay nel routing o nei redirect di login necessari; aditus-pay=success non è mai un'autorizzazione. Fornisci una sessione valida per la stessa identità fidata e publicKey. Mantieni cartScope e non cancellare il percorso né avviare un secondo checkout per aggirare un ritorno pendente, scaduto o incerto.

Vuoi invece un nuovo inizio deliberato: un vero pulsante "ricomincia da capo"? Il pacchetto esporta clearJourney(): chiamalo prima del montaggio (o del rimontaggio) e il record del viaggio persistente localmente per la pagina corrente viene eliminato, quindi il montaggio successivo inizia da capo dal punto di ingresso. Viene rimosso solo il puntatore di ripristino locale; qualsiasi stato del carrello lato server rimane intatto.

Punto di ingresso: home evento, articoli o voucher

Il punto di ingresso è deciso dal server alla creazione della sessione, mai dal browser. Senza eventSlug compare la panoramica eventi. Con eventSlug, startMode sceglie gli articoli (predefinito), la home o il modulo voucher; assortment limita gli articoli.

La selezione articoli e la continuazione dopo un voucher seguono il percorso basato sui suggerimenti del negozio originale. Senza offerte upsell utilizzabili né cross-selling, si passa direttamente alla personalizzazione dei biglietti tramite i normali controlli di login/sessione; con cross-selling, si mostra il carrello. Un'offerta upsell utilizzabile apre prima il dialogo. Salta porta alla personalizzazione senza cross-selling, oppure al carrello con cross-selling. Un upgrade confermato porta al carrello; chiudere il dialogo lascia invariata la selezione. Il percorso non salva mai la registrazione in background.

Gli assortimenti visibili possono avere accessi diretti. Se ne viene fissato uno, la home mostra solo la sua azione biglietti, non l'elenco completo né l'azione voucher.

startMode: "home" apre la pagina iniziale dell'evento. Qui si sceglie Acquista biglietti o Riscatta voucher; aprirla non crea carrelli né riscatta codici. Acquista biglietti apre gli articoli (limitati da assortment, se impostato); Riscatta voucher apre il modulo del codice. Senza eventSlug compare prima la lista eventi e poi la home dell'evento scelto. Un carrello voucher preparato o un percorso ripristinabile ha la precedenza.

// Server side: use the same session route as above, only the body varies.
// You build user and your backend's login/session route yourself.
// eventSlug sets the event. startMode also works without a slug (event
// selection first, then the mode); only assortment needs the slug
// (otherwise 400 start_option_requires_event_slug).

// 1) Article start (default): the event's article selection
const bodyArticles = { publicKey, email: user.email, eventSlug: "ExperienceDaysv52024" };

// 2) Assortment start: only one assortment (id or exact name, case-insensitive)
const bodyAssortment = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  assortment: "Pressetickets",
};

// 3) Voucher start: "Redeem voucher / register ticket" first
const bodyVoucher = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  startMode: "voucher" as const,
};

const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify(bodyVoucher),
});
const { sessionToken }: { sessionToken: string } = await res.json();

/* Voucher form: the same tokens and role hooks as the rest of the journey */
.aditus-shop__voucher-panel  { /* panel around hints + form (general panel hook) */ }
.aditus-shop__voucher-hints  { /* the two hint lines */ }
.aditus-shop__voucher-form   { /* form */ }
.aditus-shop__voucher-input  { /* code field (also .aditus-shop__field-input) */ }
.aditus-shop__voucher-redeem { /* "Redeem" button (data-variant="primary") */ }
.aditus-shop__field-error    { /* rejection reason, role="alert" */ }
/* Event home page and event actions: structured expert hooks */
.aditus-shop__home             { /* home page; root data-step="home" */ }
.aditus-shop__home-info        { /* event information */ }
.aditus-shop__home-info-head   { /* heading and logo */ }
.aditus-shop__home-info-name   { /* event name */ }
.aditus-shop__home-info-date   { /* date */ }
.aditus-shop__home-info-venue  { /* venue */ }
.aditus-shop__home-info-desc   { /* description */ }
.aditus-shop__home-actions[data-variant="tiles"] { /* tiles, alternatively compact */ }
.aditus-shop__home-action[data-kind="articles"] { /* buy tickets; also home / voucher / assortment */ }
.aditus-shop__home-action-icon    { /* icon */ }
.aditus-shop__home-action-body    { /* text group */ }
.aditus-shop__home-action-title   { /* label */ }
.aditus-shop__home-action-desc    { /* optional description */ }
.aditus-shop__home-action-chevron { /* arrow */ }
/* Phase hook: [data-step="voucher"] on the root */

Link voucher: riscattare un codice dall'URL

I voucher vengono spesso inviati come link alla tua pagina con il codice come parametro di query, es. …/tickets?code=ED24-ADITUS. Il micro-frontend può prendere in carico quel codice e riscattarlo senza che il visitatore digiti nulla. Esistono due vie di consegna; entrambe finiscono nella stessa chiamata di riscatto e si comportano poi in modo identico.

// Voucher links point to your site: https://your-site.com/tickets?code=ED24-ADITUS
// The route, request and authentication below are examples for your own website.
// The parameter name is up to you: here "code".

// Option A (browser): the micro-frontend reads the parameter itself.
import { mount } from "@aditus/shop-embed";

mount(document.getElementById("aditus-shop")!, {
  publicKey: "pk_your_site",
  sessionToken,                 // session with eventSlug (article or voucher start)
  voucherCodeParam: "code",     // read ?code=… once, remove it from the address bar, redeem it
});
// Web Component: <aditus-shop public-key="pk_your_site" voucher-code-param="code"></aditus-shop>

// Option B (server): your backend hands the code over when it creates the session.
// (Express example; the code never goes into the session response, only into the session context.)
app.get("/tickets", async (req, res) => {
  const code = typeof req.query.code === "string" ? req.query.code : undefined;
  const r = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: req.user?.email,
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher",       // or omit: article start, the code lands in the first cart
      voucherCode: code,          // undefined = normal start without a code
    }),
  });
  const { sessionToken }: { sessionToken: string } = await r.json();
  // The page additionally mounts with voucherCodeParam: "code" so that ?code= disappears
  // from the address bar (the session code wins, it is redeemed only once).
  res.render("tickets", { sessionToken });
});

Opzionale: riservare il voucher durante la creazione della sessione lato server

Se il tuo sito vuole gestire il rifiuto prima di aprire il micro-frontend, imposta redeemVoucherOnMint: true nel POST /api/shop/session fidato. A differenza della normale consegna del codice, viene creato un carrello per l'utente autenticato e il voucher vi viene riservato realmente prima di emettere la sessione: non è una richiesta di verifica aggiuntiva. Se riesce, passa al browser solo sessionToken. Il micro-frontend riprende lo stesso carrello senza crearne un altro né riscattare due volte, in modalità voucher o articles. Senza l'opzione vale la normale consegna di voucherCode.

Questa modalità richiede voucherCode, eventSlug fissato, utente identificato (email, non anonimo) e header Idempotency-Key. È disponibile solo sul backend con mint secret, non tramite POST /shop/embed-session nel browser. Supporta codici voucher/biglietto, non PromotionCode. Il codice è riservato nel carrello, ma il biglietto non è ancora registrato o emesso: servono ancora registrazione e checkout, che potrebbero essere rifiutati più avanti.

// Server side of your website: one voucher attempt, no additional check call.
// You implement the authentication and storage of this attempt yourself.
// attemptKey is a random id your backend stores durably per logical redemption
// attempt (e.g. crypto.randomUUID()). On network errors, resend the same id
// and the SAME body; never generate a new one before a retry.
async function prepareVoucherSession(
  user: { email: string },
  code: string,
  attemptKey: string,
) {
  const response = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
      "Content-Type": "application/json",
      "Idempotency-Key": attemptKey,
    },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: user.email, // only from your authenticated server session
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher", // or "articles"
      voucherCode: code,
      redeemVoucherOnMint: true,
    }),
  });
  const result: {
    sessionToken?: string; expiresAt?: number; voucherRedeemed?: boolean;
    error?: string; reason?: string; upstreamStatus?: number;
  } = await response.json();

  if (response.ok && result.sessionToken && result.voucherRedeemed === true) {
    // Only now pass it to the browser and mount the embed.
    return { sessionToken: result.sessionToken, expiresAt: result.expiresAt };
  }
  if (response.status === 422 && result.error === "voucher_rejected") {
    // Your own UI: handle the business rejection using reason, do not open the embed.
    // Translate only documented reason values into your own texts.
    return { rejected: result.reason };
  }
  if (response.status === 409 && result.error === "voucher_preparation_uncertain") {
    // Uncertain stays uncertain; a repeated POST never turns it into a success.
    // If the Shop API cannot provide the cart id, manual clarification is needed.
    throw new Error("Redemption uncertain; clarify with ADITUS, do not book again.");
  }
  if (response.status === 410 && result.error === "voucher_preparation_expired") {
    throw new Error("Prepared session no longer valid; no blind new session.");
  }
  // 400 = invalid request/key, 409 = conflict/attempt in progress,
  // 502/503 voucher_upstream_error = infrastructure, not a business error.
  throw new Error(`Session creation not completed (${response.status})`);
}

422 voucher_rejected con reason sanificato è un rifiuto di dominio: mostralo sul tuo sito, senza montare il micro-frontend senza token. 400 indica configurazione/chiave invalida; 409 idempotency_conflict indica la stessa chiave usata con dati diversi. Un'operazione pendente/incerta, 502/503 o un timeout non sono un voucher invalido. Conserva Idempotency-Key casuale per ciascun tentativo logico sul server; ritenta solo con la stessa chiave e gli stessi dati: la prenotazione potrebbe già esistere. Non registrare codici, email, errori grezzi o token.

Una creazione di sessione riuscita può lasciare un carrello prenotato anche se la pagina non viene aperta. La pulizia dei carrelli noti dopo rifiuto/revoca è best effort; un processo all'avvio e ogni 60 secondi riprova fino a 25 record per ciclo. Stessa chiave e stessi dati restituiscono il risultato completato ancora valido. Se il token originale è scaduto, revocato, completato, cancellato o trasferito, ritorna 410 voucher_preparation_expired: non ricreare la prenotazione alla cieca. Un successore autorizzato può estendere/trasferire la preparazione al primo accesso al carrello. Cancellare l'URL non libera la prenotazione.

Errori esatti: 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (o normali errori di validazione); 422 voucher_rejected contiene reason e upstreamStatus, mai codice o messaggio upstream grezzo. Possibili motivi: unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict significa input diversi; voucher_preparation_pending include Retry-After: 2 secondi, mentre voucher_preparation_uncertain resta incerto anche nei retry (nessun successo automatico successivo). 410 voucher_preparation_expired impedisce di ripetere la preparazione originale. 502/503 voucher_upstream_error indica un errore upstream. Se è stato creato un carrello ma non è arrivato il suo ID, l'API disponibile non permette riconciliazione o rilascio automatico: lo stato incerto viene conservato e il server non crea un altro carrello al retry. Occorre una verifica manuale con ADITUS prima di un nuovo tentativo. Se session-context non si carica, il micro-frontend mostra un errore con retry senza creare un nuovo carrello.

Prova tutte e tre le varianti dal vivo nell'Integration Tester: genera una sessione con eventSlug, scegli startMode o un assortimento, monta e osserva il log delle richieste. Il sistema demo accetta il voucher di prova ED24-ADITUS su ExperienceDaysv52024 (ogni riscatto riserva il biglietto per circa 20 minuti; tornare indietro lo libera). Apri l'Integration Tester

Facoltativo: naviga in modo anonimo, accedi al momento del pagamento

Non è necessario sapere in anticipo chi è l'utente. Monta con una sessione ospite e il micro-frontend consente a un visitatore anonimo di sfogliare eventi, scegliere articoli e riempire il carrello. Solo quando superano il carrello, verso la registrazione e il pagamento, ti viene chiesto di stabilire l'utente reale, tramite il callback onUserRequired. Il resto del flusso prosegue poi con il carro conservato.

1. 1

   Montare con una sessione ospite

   Per attivare il negozio è comunque necessario un token di sessione, ma può essere una sessione ospite: basta crearla senza il campo e-mail, non è necessario alcun indirizzo segnaposto. Il visitatore naviga e riempie il carrello sottostante.

2. 2

   L'abbandono del carrello attiva l'onUserRequired

   Nel momento in cui il visitatore avanza oltre il carrello, il micro-frontend richiama una volta la tua richiamata e mostra uno stato in sospeso neutro. Autentica l'utente (login/SSO), quindi crea una nuova sessione vincolata all'utente esattamente nello stesso modo della prima: server-server con il tuo segreto. Anche l'utente successivo viene stabilito tramite la creazione della sessione da server a server: il segreto non raggiunge mai il browser e l'utente non viene mai impostato nel codice client. La tua richiamata trasmette solo il token opaco risultante. Fondamentalmente, il tuo backend deriva quell'identità dalla propria sessione autenticata (cookie/JWT); non deve mai accettare l'e-mail o l'ID utente dal browser, altrimenti un visitatore malintenzionato potrebbe richiedere la sessione di qualcun altro e leggere i suoi dati personali tramite la precompilazione.

3. 3

   Restituisci il nuovo gettone: il carrello viene trasferito

   Restituisci il nuovo token di sessione e il micro-frontend lo scambia e lega l'utente identificato al carrello esistente: il carrello, i suoi articoli e le eventuali fasce orarie rimangono invariati. Quindi entra nella registrazione. Restituisci null per interrompere: il visitatore rimane semplicemente sul carrello, nessun errore.

4. 4

   Omettere onUserRequired per un utente fisso

   Se si lascia fuori il callback, non cambia nulla rispetto al flusso classico: si monta una sessione associata all'utente e il micro-frontend agisce come quell'utente fin dal primo passaggio.

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// A guest session token is enough to mount: created server-to-server as
// usual, just without the email field (no placeholder address needed). The
// visitor may browse and fill the cart before a specific user is known.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",
  sessionToken: guestSessionToken,

  // Called once as soon as the visitor leaves the cart towards registration.
  // This is where you authenticate the user (login/SSO) and create a new,
  // user-bound session server-to-server.
  // Return the fresh token -> the micro-frontend adopts it and rebuilds the
  // cart under the identified user (articles are kept). Return null to
  // cancel -> the visitor stays in the cart, without an error.
  onUserRequired: async () => {
    // Calls only your backend, with no identity in the payload. Your backend reads
    // the signed-in user from its own session (cookie/JWT) and creates the session
    // server-side for exactly this identity. Never pass the email from the browser,
    // otherwise an attacker could insert someone else's address here and reach
    // that person's personal data through the prefill.
    // host.loginAndMintSession(): Promise<string | null> is your own function.
    // Implement login/SSO + authenticated backend call + server-side session creation on your website.
    // On cancel the function returns null; on failure it throws explicitly.
    return host.loginAndMintSession();
  },
};

const handle: ShopHandle = mount(el, config);

GA4/eventi e-commerce (facoltativo)

Il micro-frontend può segnalare la canalizzazione dello shopping alle tue analisi, ma solo se lo chiedi. Non include gtag, GTM e GA SDK, non carica nulla, non imposta cookie e non invia nulla da solo. Aggiungi una richiamata facoltativa, onEvent, e ricevi eventi digitati già modellati nello schema di e-commerce avanzato GA4 di Google. Ometti onEvent e non cambia nulla. Quale strumento fornisci e se hai il consenso per l'invio, rimane interamente dalla tua parte.

import {
  mount,
  type ShopHandle,
  type ShopAnalyticsEvent,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_your_site",
  sessionToken,
  // Optional. If you leave out onEvent, nothing changes: the micro-frontend
  // sends nothing, loads no gtag/GTM/GA SDK and sets no cookies.
  // Tool, consent and mapping stay entirely with you. This example uses GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent is yours: only send once the user has agreed.
    if (!hasAnalyticsConsent()) return;
    // The events already follow the GA4 schema (name + items/value/currency ...),
    // so pass them to gtag 1:1.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey e sessionToken

Mantieni i due separati. Rispondono a domande diverse e sono accoppiati, non intercambiabili.

Riferimento all'endpoint e alla risposta

Entrambe le chiamate partono dal tuo backend: si autentica con il mint secret del tuo client (generato nella console di amministrazione ADITUS) come token Bearer. Una sessione per login è lo schema normale; il browser vede solo il token risultante. I siti senza backend non usano questi endpoint: l'elemento crea da sé la propria sessione browser tramite POST /api/shop/embed-session, limitato al dominio (public-key con cart-scope="tab").

Puoi provare questo flusso esatto con le tue credenziali nel filetester di integrazione. Crea una sessione, esegui il mount e percorri il flusso.

Creare una sessione: richiesta

Creare una sessione: risposta (200)

Revoca una sessione

DELETE /api/shop/session/:token بنفس سر Bearer. يجب أن ينتمي السر إلى العميل الذي أُنشئت الجلسة له. استدعِه عند تسجيل الخروج أو إعادة ضبط الكشك حتى ينتهي الرمز مع جلستك. بالنسبة للجلسات المجهولة (المرتبطة بالرمز) يحذف الاستدعاء أيضًا سلال الجلسة في Shop API، وتُحرَّر حجوزات القسائم التي تحتفظ بها تلك السلال فورًا وليس عند انتهاء صلاحية السلة. الاستجابة: { "revoked": true, "carts": { "scope": "token", "deleted": 1, "failed": 0 } } (revoked false إذا كانت الجلسة منتهية بالفعل؛ scope "identity" للجلسات المرتبطة بمستخدم، التي تبقى سلالها بعد رمز واحد ولا تُمس). الإلغاء متكرر الأثر ويمكن إرساله دون انتظار النتيجة.

Letture server-to-server

Un backend che pilota il micro-frontend (una shell per chiosco, uno shop in loco) di solito ha bisogno di dati del tenant prima di creare una sessione: quali eventi esistono e sono in vendita, quali lingue parla lo shop, quali liste di riferimento e quale branding si applicano. Quattro endpoint di lettura rispondono con le stesse credenziali usate per creare la sessione (segreto Bearer + header X-Aditus-Public-Key, stesso rate limit, Cache-Control: no-store). Sono proiezioni filtrate della Shop API, mai un inoltro grezzo; ?language= (o Accept-Language, predefinito de) sceglie la lingua dei nomi. Errori: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Gli errori sono espliciti