Ticketshop nativ einbetten

Schnellstart

Es gibt zwei Wege zum laufenden Shop. Beide nutzen dasselbe Script und dasselbe Element; sie unterscheiden sich darin, wer die Session erstellt.

Ohne Backend

Das Element erstellt selbst eine Browser-Session für deinen publicKey, beschränkt auf die freigegebenen Domains. Setze cart-scope="tab": ohne Server-Identität endet der Standard "shared" in einem expliziten Fehler. Jeder Browser-Tab hat dann seinen eigenen Warenkorb. Die Session ist anonym: Besucher stöbern und füllen den Warenkorb. Vor der Registrierung muss element.config.onUserRequired einen nutzergebundenen Session-Token von einem Server liefern; ohne ihn endet der Shop mit einem Hinweis im Warenkorb.

<!-- 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>

Mit Backend

Dein Server erstellt die Session mit dem Mint-Secret und legt fest, wer der Käufer ist. Übergib den zurückgegebenen Token an das Element. Mit einer Käufer-E-Mail hält der Standard cart-scope "shared" einen gemeinsamen Warenkorb über alle Tabs.

// 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>

Ersetze pk_your_site durch deinen Publishable Key aus dem ADITUS-Admin. developers.aditus.com ist die Produktionsadresse für Script und API. Beide Wege sind weiter unten ausführlich beschrieben.

Die Technologie hinter dem Micro-Frontend

Das Micro-Frontend rendert den kompletten Kaufprozess (Events, Artikel, Warenkorb, Registrierung, Zahlung, Abschluss) in das DOM deiner Seite. Es nutzt das Layout deiner Seite, und dein CSS kann jeden Teil davon gestalten.

Deine Website ist vertrauenswürdig: Dein Server authentifiziert den Nutzer, bevor er eine identifizierte Session erstellt. Das Embed läuft bewusst im Light DOM deiner Seite, ohne iFrame-Isolation. Scripts deiner Seite können auf DOM und Browser-Speicher zugreifen; sichere deshalb deine Seite und ihre Drittanbieter-Scripts ab. Origin-Autorisierung per Public Key ist keine Nutzerauthentifizierung. Zahlungszugangsdaten werden nur auf der externen Seite des Zahlungsanbieters eingegeben.

Zahlungssicherheit, PCI & CSP

Die Kaufvorbereitung rendert in deiner Seite. Die Zahlung selbst findet auf der Seite des Zahlungsanbieters statt, daher laufen keine Zahlungsdaten durch deine Seite.

Vergleich mit iFrame und Shadow-DOM

Die Ansätze im Vergleich

Alternative: Quellpaket (selbst ausgeliefert)

Alternativ lädst du das Quellpaket von deiner ADITUS-Instanz herunter und bündelst es in deine App (Vite, webpack, Next.js oder Nuxt). Diese Auslieferung verwaltest du selbst: Updates erfordern Neuinstallation, Build und Deployment. Es liegt nicht auf öffentlichem npm.

SSR-Apps: Next.js & Nuxt

Das Micro-Frontend ist bewusst client-only. Sein Inhalt ist live und session-gebunden: Verfügbarkeiten, Preise und der Warenkorb des Käufers existieren nur für eine authentifizierte Session zum Abrufzeitpunkt. Es gibt also nichts Sinnvolles, das dein Server vorrendern könnte. mount() erzeugt einen frischen client-seitigen React-Root (createRoot); server-gerendertes Markup im Container wird nicht hydriert. Genau das macht die SSR-Integration einfach und vorhersehbar: auf dem Server einen Platzhalter rendern, im Client mounten, den Platz reservieren. So springt nichts.

// Next.js (App Router): Das Micro-Frontend ist bewusst 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_deine_seite",
      sessionToken, // server-seitig ausgestellt, als Prop an die Client-Komponente
      cartScope: "shared", // Standard auch im Framework; vertrauenswürdige Server-Identität
    });
    return () => handle(); // Unmount beim Routenwechsel
  }, [sessionToken]);

  // Server und Client rendern DENSELBEN Platzhalter und vermeiden damit einen Hydration-Mismatch.
  // min-height reserviert den Platz, damit die Seite beim Mount nicht springt (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

Das Micro-Frontend braucht eine Session

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

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// Ohne sessionToken bleibt das Micro-Frontend inaktiv: es zeigt nur einen
// neutralen Hinweis und startet keine API-Calls: kein Warenkorb,
// keine Registrierung, kein Checkout. Erst eine Session aktiviert den Shop.
mount(el, {
  publicKey: "pk_deine_seite",
  // sessionToken fehlt -> Shop wird nicht aktiviert.
});

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

// getElementById kann null sein. Prüfe dies in TypeScript sauber statt mit "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// AditusShopConfig typisiert alle Optionen und bietet Autovervollständigung.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_deine_seite", // Pflicht, sobald eine Session im Spiel ist
  sessionToken,                // vom Backend ausgestellt, nur im Speicher halten
  cartScope: "shared",          // Standard; vertrauenswürdige Server-Identität erforderlich
};

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

// Das Micro-Frontend sendet bei jedem Shop-Call den Header X-Aditus-Session.
// Beim Logout die Session serverseitig widerrufen und neu mounten/aktualisieren.

Beim Reload kann das Embed mit einem gültigen Journey-Verweis den Live-Warenkorb unter demselben autorisierten Scope und derselben vertrauenswürdigen Identität vom Server laden. Der Verweis ist keine Autorisierung und garantiert keine Wiederherstellung nach Session-/Warenkorbablauf, Speicherlöschung oder Nutzerwechsel. Explizites tab führt Journeys anderer Tabs nicht zusammen; der Standard shared erzwingt weiterhin die Checkout-Sperre mit nur einem Schreiber.

Die Zahlungsrückkehr nutzt aditus-return (einen opaken, kurzlebigen, servergebundenen Rückkehr-Token) plus aditus-pay. Sie kann im selben oder in einem neuen Tab erfolgen; der Server verlangt aber einen autorisierten Client/eine autorisierte Origin und die passende vertrauenswürdige Identität. Rückkehr-Queryparameter sind kein Kaufnachweis. Der Server klärt den Zahlungsstatus und finalisiert den tokengebundenen Versuch; ein unbekannter Ausgang bleibt zur Klärung gesperrt, statt blind als neuer Kauf wiederholt zu werden. Abgelaufene oder unautorisierte Rückkehrversuche liefern explizite Fehler, keine Erlaubnis für eine Ersatzbestellung.

Die Zuweisung eines Zahlungsanbieters bereitet die Zahlung nur vor: Die Zusammenfassung bleibt bearbeitbar. Die Sperre beginnt erst beim tatsächlichen Absprung nach den erforderlichen Zustimmungen. Ein cancel-/error-Rückkehrparameter beweist keinen Fehlschlag: Das Backend prüft den Warenkorb erneut; Completed mit order.id bestätigt den Abschluss. Erst die bestätigt erfolgreiche Entfernung der Anbieterzuweisung für denselben Warenkorb erlaubt einen erneuten Versuch; unklare Ausgänge bleiben gesperrt und können erneut geprüft werden. Das garantiert weder eine Erstattung noch den Ausschluss einer späteren Zahlungsabwicklung.

Absprung zur Zahlungsseite: was deine Seite für die Session tun muss

• Liefere die konfigurierte Rückkehr-URL mit gemountetem Embed aus. Erhalte aditus-return und aditus-pay beim Routing oder bei nötigen Login-Redirects; behandle aditus-pay=success niemals als Autorisierung. Stelle eine gültige Session für dieselbe vertrauenswürdige Identität und denselben publicKey bereit. Behalte den gewählten cartScope bei und lösche weder die Journey noch starte einen zweiten Checkout, um eine laufende, abgelaufene oder unklare Rückkehr zu umgehen.

Du willst stattdessen bewusst von vorn beginnen, etwa mit einem echten "Neu starten"-Button? Das Paket exportiert clearJourney(): Rufe es vor dem Mounten (oder Re-Mounten) auf, und der lokal gespeicherte Journey-Datensatz der aktuellen Seite wird gelöscht. Der nächste Mount startet frisch am Einstiegspunkt. Es wird nur der lokale Wiederaufnahme-Zeiger entfernt; serverseitiger Warenkorb-Zustand bleibt unberührt.

Einstiegspunkt: Veranstaltungsstartseite, Artikel oder Gutschein

Wo die Journey beginnt, entscheidet dein Server beim Erstellen der Session, nie der Browser. Ohne eventSlug öffnet das Micro-Frontend die Veranstaltungsübersicht. Mit eventSlug wählst du per startMode Artikelauswahl (Standard), Veranstaltungsstartseite oder Gutscheinmaske; assortment beschränkt die Artikelauswahl.

Artikelauswahl und Weitergehen nach Gutscheineinlösung folgen der empfehlungsbasierten Route des ursprünglichen Shops. Ohne nutzbares Upsell-Angebot und ohne Cross-Selling geht es direkt zur Ticketpersonalisierung durch die normalen Login-/Session-Prüfungen; mit Cross-Selling zum Warenkorb. Ein nutzbares Upsell-Angebot öffnet zuerst den Dialog. Überspringen führt ohne Cross-Selling zur Personalisierung, mit Cross-Selling zum Warenkorb. Ein bestätigtes Upgrade führt zum Warenkorb; Schließen des Dialogs lässt die Auswahl stehen. Die Navigation schreibt keine Registrierung im Hintergrund.

Im Shop sichtbare Sortimente können eigene Direkteinstiege erhalten. Ist ein Sortiment festgelegt, zeigt die Startseite nur dessen Ticket-Aktion – weder die volle Liste noch die Gutschein-Aktion.

startMode: "home" öffnet die Veranstaltungsstartseite. Besucher wählen dort Tickets kaufen oder Gutschein einlösen; das bloße Öffnen legt keinen Warenkorb an und löst keinen Code ein. Tickets kaufen öffnet die Artikelauswahl (gegebenenfalls auf assortment beschränkt), Gutschein einlösen die Code-Maske. Ohne eventSlug erscheint zuerst die Veranstaltungsübersicht und danach die Startseite des gewählten Events. Ein vorbereiteter Gutschein-Warenkorb oder eine wiederaufnehmbare Journey hat Vorrang vor einem neuen Einstieg.

// Server-Seite: Verwende dieselbe Session-Route wie oben, nur der Body variiert.
// user und die Login-/Session-Route deines Backends baust du selbst.
// eventSlug legt das Event fest. startMode geht auch ohne Slug (Eventauswahl
// zuerst, dann der Modus); nur assortment braucht den Slug
// (sonst 400 start_option_requires_event_slug).

// 1) Artikelstart (Standard): Artikelauswahl des Events
const bodyArticles = { publicKey, email: user.email, eventSlug: "ExperienceDaysv52024" };

// 2) Sortimentsstart: nur ein Sortiment (Id oder exakter Name, Groß-/Kleinschreibung egal)
const bodyAssortment = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  assortment: "Pressetickets",
};

// 3) Gutscheinstart: zuerst "Gutschein einlösen / Ticket registrieren"
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();

/* Gutschein-Maske: dieselben Tokens und Rollen-Hooks wie der Rest der Journey */
.aditus-shop__voucher-panel  { /* Panel um Hinweise + Formular (general panel hook) */ }
.aditus-shop__voucher-hints  { /* die beiden Hinweiszeilen */ }
.aditus-shop__voucher-form   { /* Formular */ }
.aditus-shop__voucher-input  { /* Codefeld (zusätzlich .aditus-shop__field-input) */ }
.aditus-shop__voucher-redeem { /* "Einlösen"-Button (data-variant="primary") */ }
.aditus-shop__field-error    { /* Ablehnungsgrund, role="alert" */ }
/* Veranstaltungsstartseite und Event-Aktionen: strukturierte Expert-Hooks */
.aditus-shop__home             { /* Startseite; Root data-step="home" */ }
.aditus-shop__home-info        { /* Event-Informationen */ }
.aditus-shop__home-info-head   { /* Überschrift und Logo */ }
.aditus-shop__home-info-name   { /* Eventname */ }
.aditus-shop__home-info-date   { /* Datum */ }
.aditus-shop__home-info-venue  { /* Veranstaltungsort */ }
.aditus-shop__home-info-desc   { /* Beschreibung */ }
.aditus-shop__home-actions[data-variant="tiles"] { /* Kacheln, alternativ compact */ }
.aditus-shop__home-action[data-kind="articles"] { /* Tickets kaufen; auch home / voucher / assortment */ }
.aditus-shop__home-action-icon    { /* Icon */ }
.aditus-shop__home-action-body    { /* Textgruppe */ }
.aditus-shop__home-action-title   { /* Beschriftung */ }
.aditus-shop__home-action-desc    { /* optionale Beschreibung */ }
.aditus-shop__home-action-chevron { /* Pfeil */ }
/* Phase-Hook: [data-step="voucher"] auf dem Root */

Gutschein-Links: Code aus der URL einlösen

Gutscheine werden oft als Link auf deine Seite verschickt, mit dem Code als Query-Parameter, z. B. …/tickets?code=ED24-ADITUS. Das Micro-Frontend kann diesen Code übernehmen und einlösen, ohne dass jemand etwas tippen muss. Es gibt zwei Übergabewege; beide münden im selben Einlöse-Aufruf und verhalten sich danach identisch.

// Gutschein-Links zeigen auf deine Seite: https://deine-seite.de/tickets?code=ED24-ADITUS
// Route, Request und Authentisierung unten sind Beispiele für deine eigene Website.
// Der Parametername ist frei: hier "code".

// Variante A (Browser): das Micro-Frontend liest den Parameter selbst.
import { mount } from "@aditus/shop-embed";

mount(document.getElementById("aditus-shop")!, {
  publicKey: "pk_deine_seite",
  sessionToken,                 // Session mit eventSlug (Artikel- oder Gutscheinstart)
  voucherCodeParam: "code",     // ?code=… einmal lesen, aus der Adresszeile entfernen, einlösen
});
// Web Component: <aditus-shop public-key="pk_deine_seite" voucher-code-param="code"></aditus-shop>

// Variante B (Server): dein Backend übernimmt den Code beim Erstellen der Session.
// (Express-Beispiel; der Code wandert nie in die Session-Antwort, sondern in den Session-Kontext.)
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_deine_seite",
      email: req.user?.email,
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher",       // oder weglassen: Artikelstart, Code landet im ersten Warenkorb
      voucherCode: code,          // undefined = normaler Start ohne Code
    }),
  });
  const { sessionToken }: { sessionToken: string } = await r.json();
  // Seite mountet zusätzlich mit voucherCodeParam: "code", damit ?code= aus der Adresszeile
  // verschwindet (der Session-Code gewinnt, eingelöst wird nur einmal).
  res.render("tickets", { sessionToken });
});

Optional: Gutschein schon beim Erstellen der Session reservieren

Soll deine Website einen abgelehnten Gutschein vor dem Öffnen des Embeds selbst behandeln, setze redeemVoucherOnMint: true beim vertrauenswürdigen POST /api/shop/session. Anders als die normale voucherCode-Übergabe legt das einen Warenkorb für den authentifizierten Nutzer an und reserviert den Gutschein dort wirklich, bevor die Session-Erstellung erfolgreich ist – kein zusätzlicher Vorab-Prüfrequest. Bei Erfolg gib nur den erhaltenen sessionToken an den Browser weiter. Das Embed übernimmt DENSELBEN Warenkorb ohne Neuanlage oder zweite Einlösung, sowohl bei startMode voucher als auch articles. Ohne die Option gilt die normale voucherCode-Übergabe.

Dieser Modus braucht voucherCode, einen festen eventSlug, einen identifizierten Nutzer (email; nicht anonym) und den Header Idempotency-Key. Er ist nur mit Mint-Secret auf deinem Backend verfügbar, nicht über POST /shop/embed-session im Browser. Er unterstützt Gutschein-/Ticketcodes, keine PromotionCodes. Der Code wird im Warenkorb reserviert, nicht bereits als Ticket registriert oder ausgegeben: Registrierung und Abschluss folgen. Spätere Prüfungen der Shop-API können noch scheitern; eine erfolgreiche Session-Erstellung garantiert keine fertige Ticketausgabe.

// Server-Seite deiner Website: ein Gutschein-Versuch, kein zusätzlicher Prüf-Call.
// Authentisierung und Speicherung dieses Versuchs implementierst du selbst.
// attemptKey ist eine von deinem Backend pro logischem Einlöseversuch dauerhaft gespeicherte
// Zufalls-ID (z. B. crypto.randomUUID()). Bei Netzwerkfehlern dieselbe ID
// und DENSELBEN Body erneut senden, nie vor einem Retry neu erzeugen.
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_deine_seite",
      email: user.email, // nur aus deiner authentifizierten Server-Session
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher", // oder "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) {
    // Erst jetzt an den Browser reichen und das Embed mounten.
    return { sessionToken: result.sessionToken, expiresAt: result.expiresAt };
  }
  if (response.status === 422 && result.error === "voucher_rejected") {
    // Eigene Oberfläche: fachliche Ablehnung mit reason behandeln, kein Embed öffnen.
    // Nur freigegebene reason-Werte in eigene Texte übersetzen.
    return { rejected: result.reason };
  }
  if (response.status === 409 && result.error === "voucher_preparation_uncertain") {
    // Unklar bleibt unklar; kein automatischer Erfolg durch erneutes POST.
    // Kann die Shop-API die Cart-ID nicht liefern, ist manuelle Klärung nötig.
    throw new Error("Einlösung unklar; mit ADITUS klären, nicht neu buchen.");
  }
  if (response.status === 410 && result.error === "voucher_preparation_expired") {
    throw new Error("Vorbereitete Session nicht mehr gültig; keine blinde neue Session.");
  }
  // 400 = ungültiger Request/Key, 409 = Konflikt/laufender Versuch,
  // 502/503 voucher_upstream_error = Infrastruktur, kein Fachfehler.
  throw new Error(`Session-Erstellung nicht abgeschlossen (${response.status})`);
}

422 voucher_rejected mit bereinigtem reason ist eine fachliche Ablehnung: Zeige sie auf deiner Website und mounte ohne Token kein Embed. Ungültige Konfiguration/Key ergibt 400; 409 idempotency_conflict bedeutet gleicher Key mit anderen Eingaben, während ein laufender/unklarer Versuch kein ungültiger Gutschein ist. 502/503 und Netzwerk-Timeouts sind Infrastruktur-/unklare Ergebnisse, keine Gutscheinablehnung. Speichere einen neuen zufälligen Idempotency-Key pro logischem Versuch auf deinem Server und wiederhole nur mit demselben Key und exakt denselben Eingaben. Nach unklarem Ausgang niemals mit neuem Key wiederholen: Die Reservierung könnte bereits existieren. Code, E-Mail, rohe API-Fehler und Session-Token nicht protokollieren.

Eine erfolgreiche Session-Erstellung kann einen reservierten Warenkorb hinterlassen, selbst wenn der Käufer die Seite nie öffnet. Das Aufräumen eines bekannten Warenkorbs nach Ablehnung/Widerruf erfolgt bestmöglich; ein Sweeper beim Start und danach alle 60 Sekunden wiederholt bis zu 25 Datensätze je Lauf. Gleicher Key und gleiche Eingabe liefern bei gültigem abgeschlossenen Versuch dasselbe Ergebnis. Ist der ursprüngliche Token abgelaufen, widerrufen, abgeschlossen, gelöscht oder übertragen, kommt stattdessen 410 voucher_preparation_expired – die Reservierung nicht blind neu anlegen. Ein berechtigter Nachfolger kann die Vorbereitung beim ersten Warenkorbzugriff verlängern oder übernehmen. Den Code aus der URL deiner Seite zu entfernen, gibt keine Reservierung frei.

Genaue Fehler bei der Session-Erstellung: 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (oder normale Validierung); 422 voucher_rejected enthält reason und upstreamStatus, niemals den rohen Fehlercode oder -text der Shop-API. Mögliche Gründe: unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict bedeutet andere Eingaben; voucher_preparation_pending liefert Retry-After: 2 Sekunden, voucher_preparation_uncertain bleibt auch bei Wiederholung unklar (kein automatisch späterer Erfolg). 410 voucher_preparation_expired heißt: die ursprüngliche Vorbereitung ist nicht mehr abrufbar. 502/503 voucher_upstream_error bedeutet einen Fehler im ADITUS-Ticketsystem. Hat die Shop-API einen Warenkorb angelegt, aber dessen ID nicht zurückgeliefert, sind automatischer Abgleich und Freigabe mit der verfügbaren API unmöglich: der unklare Datensatz bleibt erhalten und der Server legt beim Retry keinen zweiten Warenkorb an. Vor einem neuen Versuch ist eine manuelle Klärung mit ADITUS nötig. Wenn session-context nicht geladen werden kann, zeigt das Embed einen Fehler mit Wiederholungsoption statt still einen frischen Warenkorb anzulegen.

Probiere alle drei Varianten live im Integrationstester: Session mit eventSlug erstellen, startMode oder Sortiment wählen, mounten und das Request-Protokoll beobachten. Das Demo-System akzeptiert den Test-Gutschein ED24-ADITUS auf ExperienceDaysv52024 (jede Einlösung reserviert das Ticket rund 20 Minuten; Zurückgehen gibt es wieder frei). Integrationstester öffnen

Optional: anonym browsen, beim Checkout anmelden

Du musst nicht von Anfang an wissen, wer der Käufer ist. Mounte mit einer Gast-Session, und das Micro-Frontend lässt einen anonymen Besucher Events durchstöbern, Artikel wählen und den Warenkorb füllen. Erst wenn er den Warenkorb verlässt (Richtung Registrierung und Checkout) bittet es dich, den echten Nutzer festzulegen, über den Callback onUserRequired. Der restliche Ablauf läuft dann mit erhaltenem Warenkorb weiter.

1. 1

   Mit einer Gast-Session mounten

   Ein Session-Token ist weiterhin nötig, um den Shop zu aktivieren. Es kann aber eine Gast-Session sein: einfach ohne das Feld email erstellen, keine Platzhalter-Adresse nötig. Der Besucher browst und füllt den Warenkorb darunter.

2. 2

   Das Verlassen des Warenkorbs löst onUserRequired aus

   Sobald der Besucher den Warenkorb verlässt, ruft das Micro-Frontend deinen Callback einmal auf und zeigt einen neutralen Wartezustand. Authentifiziere den Nutzer (Login/SSO) und erstelle dann eine frische, nutzergebundene Session genau wie die erste: server-zu-server mit deinem Secret. Auch das spätere Festlegen des Nutzers läuft über diese serverseitige Session-Erstellung. Das Secret erreicht nie den Browser und der Nutzer wird nie im Client-Code gesetzt. Dein Callback reicht nur den entstandenen opaken Token weiter. Entscheidend: Dein Backend leitet diese Identität aus seiner eigenen authentifizierten Session ab (Cookie/JWT); es darf E-Mail oder User-ID niemals aus dem Browser entgegennehmen, sonst könnte ein böswilliger Besucher eine fremde Session anfordern und über den Prefill deren personenbezogene Daten lesen.

3. 3

   Gib den neuen Token zurück. Der Warenkorb wandert mit

   Gib den frischen Session-Token zurück; das Micro-Frontend übernimmt ihn und bindet den identifizierten Nutzer an den bestehenden Warenkorb. Warenkorb, Artikel und etwaige Zeitfenster bleiben unverändert erhalten. Danach geht es zur Registrierung. Gib null zurück, um abzubrechen. Der Besucher bleibt einfach im Warenkorb, ohne Fehler.

4. 4

   Ohne onUserRequired: fixer Nutzer

   Lässt du den Callback weg, ändert sich nichts am klassischen Ablauf: Mounte mit einer nutzergebundenen Session, und das Micro-Frontend agiert vom ersten Schritt an als dieser Nutzer.

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

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

// Ein Gast-Session-Token reicht zum Mounten: server-zu-server erstellt wie
// gehabt, nur ohne das Feld email (keine Platzhalter-Adresse nötig). Der
// Besucher darf browsen und den Warenkorb füllen, ohne dass ein konkreter
// Nutzer feststeht.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_deine_seite",
  sessionToken: guestSessionToken,

  // Wird einmal aufgerufen, sobald der Besucher den Warenkorb Richtung
  // Registrierung verlässt. Hier authentifizierst du den Nutzer (Login/SSO)
  // und erstellst server-zu-server eine neue, nutzergebundene Session.
  // Gib den frischen Token zurück -> das Micro-Frontend übernimmt ihn und baut
  // den Warenkorb unter dem identifizierten Nutzer neu auf (Artikel bleiben
  // erhalten). Gib null zurück, um abzubrechen -> der Besucher bleibt im
  // Warenkorb, ohne Fehler.
  onUserRequired: async () => {
    // Ruft nur dein Backend auf – ohne Identität im Payload. Dein Backend liest
    // den eingeloggten Nutzer aus seiner eigenen Session (Cookie/JWT) und erstellt
    // server-seitig für genau diese Identität. Niemals die E-Mail aus dem Browser
    // übergeben – sonst könnte ein Angreifer hier eine fremde Adresse einsetzen
    // und über den Prefill an deren personenbezogene Daten gelangen.
    // host.loginAndMintSession(): Promise<string | null> ist deine eigene Funktion.
    // Implementiere Login/SSO + authentisierten Backend-Call + serverseitige Session-Erstellung auf deiner Website.
    // Bei Abbruch liefert die Funktion null; bei Fehler wirft sie explizit.
    return host.loginAndMintSession();
  },
};

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

GA4- / E-Commerce-Events (optional)

Das Micro-Frontend kann den Einkaufs-Funnel an deine Analytics melden, aber nur, wenn du es darum bittest. Es bündelt kein gtag, kein GTM und kein GA-SDK, lädt nichts, setzt keine Cookies und sendet von sich aus nichts. Du ergänzt einen optionalen Callback, onEvent, und bekommst typisierte Events, die bereits im GA4-Enhanced-Ecommerce-Schema von Google geformt sind. Lässt du onEvent weg, ändert sich nichts. Welches Tool du fütterst und ob du senden darfst (Consent), bleibt komplett bei dir.

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

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount-Ziel #aditus-shop nicht gefunden");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_deine_seite",
  sessionToken,
  // Optional. Lässt du onEvent weg, ändert sich nichts: das Micro-Frontend
  // sendet nichts, lädt kein gtag/GTM/GA-SDK und setzt keine Cookies.
  // Tool, Consent und Mapping bleiben komplett bei dir. Dieses Beispiel nutzt GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent liegt bei dir: erst senden, wenn der Nutzer zugestimmt hat.
    if (!hasAnalyticsConsent()) return;
    // Die Events sind bereits im GA4-Schema (name + items/value/currency ...),
    // also 1:1 an gtag durchreichen.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey vs. sessionToken

Halte die beiden auseinander. Sie beantworten verschiedene Fragen und werden kombiniert, nicht ausgetauscht.

Endpunkt- & Antwort-Referenz

Beide Aufrufe kommen von deinem Backend: Es authentifiziert sich mit dem Mint-Secret deines Clients (erzeugt in der ADITUS-Admin-Konsole) als Bearer-Token. Eine Session pro Login ist das normale Muster; der Browser sieht nur den entstandenen Token. Websites ohne Backend nutzen diese Endpunkte nicht: Das Element erstellt seine Browser-Session selbst über den domain-beschränkten POST /api/shop/embed-session (public-key mit cart-scope="tab").

Diesen exakten Ablauf kannst du mit deinen eigenen Zugangsdaten im Integrations-Tester ausprobieren. Erstelle eine Session, mounte den Shop und durchlaufe die Journey.

Session erstellen: Request

Session erstellen: Antwort (200)

Session widerrufen

DELETE /api/shop/session/:token mit demselben Bearer-Secret. Es muss zum Client gehören, für den die Session erstellt wurde. Beim Logout oder Kiosk-Reset aufrufen, damit der Token zusammen mit deiner eigenen Session stirbt. Bei anonymen (token-gebundenen) Sessions löscht der Aufruf zusätzlich die Warenkörbe der Session in der Shop-API. Von diesen Warenkörben gehaltene Gutschein-Reservierungen werden sofort frei, nicht erst mit dem Ablauf des Warenkorbs. Antwort: { "revoked": true, "carts": { "scope": "token", "deleted": 1, "failed": 0 } } (revoked false, wenn die Session schon abgelaufen war; scope "identity" bei nutzergebundenen Sessions, deren Warenkörbe einen einzelnen Token überdauern und unangetastet bleiben). Der Widerruf ist idempotent und kann fire-and-forget gesendet werden.

Server-zu-Server-Reads

Ein Backend, das das Micro-Frontend steuert (eine Kiosk-Shell, ein Onsite-Shop) braucht meist Mandantenfakten, bevor es eine Session erstellt: welche Events es gibt und im Verkauf sind, welche Sprachen der Shop spricht, welche Lookup-Listen und welches Branding gelten. Vier Lese-Endpunkte beantworten das mit denselben Zugangsdaten wie die Session-Erstellung (Bearer Mint-Secret + Header X-Aditus-Public-Key, gleiches Rate-Limit, Cache-Control: no-store). Sie sind Whitelist-Projektionen der Shop-API, nie eine Rohweiterleitung; ?language= (oder Accept-Language, Standard de) wählt die Sprache der Namen. Fehler: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Fehler sind explizit