Nutzer setzen & Authentifizierung

Die Technologie hinter dem Micro-Frontend

Der ADITUS Ticketshop, eingewoben statt teleportiert. Das Micro-Frontend rendert den kompletten Kaufprozess nativ in deine Seite — kein iFrame, kein visueller Fremdkörper. Es ist bewusst schlank und host-nativ gebaut, damit es aussieht und sich anfühlt wie deine eigene Seite, nicht wie ein eingeblendetes Widget.

Zahlungssicherheit, PCI & CSP

Die Integration von Drittanbieter-Komponenten wie Ticketshops erfordert traditionell eine Abwägung zwischen User Experience, Performance und IT-Sicherheit. Das Micro-Frontend löst diesen Zielkonflikt durch ein hybrides Paradigma: Die Interaktionsstrecke rendert im nativen Light-DOM deiner Seite, der Bezahlvorgang bleibt strikt isoliert — alles Unkritische passiert in deiner Seite, die Zahlung selbst nie.

Abgrenzung zu den Marktalternativen

Die Ansätze im Vergleich

Bezug & Lieferform

Das Micro-Frontend liegt nicht auf dem öffentlichen npm und auf keinem CDN. Es kommt als Quellpaket direkt von deiner ADITUS-Instanz: TypeScript, ESM, vollständig typisiert, ohne eigene Runtime-Abhängigkeiten — dein Bundler (Vite, webpack, Next.js, Nuxt) kompiliert es zusammen mit deiner App wie eigenen Code. Der Import-Name in den Snippets dieser Seite (@workspace/aditus-shop-embed) ist der Paketname unserer Referenz-Integration; das herunterladbare Paket heißt @aditus/shop-embed — die API ist identisch.

SSR-Hosts: 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 ein Host-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 — nichts springt.

// Next.js (App Router) — das Micro-Frontend ist bewusst client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@workspace/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 gemintet, als Prop an die Client-Komponente
    });
    return () => handle(); // Unmount beim Routenwechsel
  }, [sessionToken]);

  // Server und Client rendern DENSELBEN Platzhalter — kein 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 "@workspace/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 "@workspace/aditus-shop-embed";

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

// AditusShopConfig typisiert alle Optionen — Autovervollständigung inklusive.
const config: AditusShopConfig = {
  publicKey: "pk_deine_seite", // Pflicht, sobald eine Session im Spiel ist
  sessionToken,                // vom Backend gemintet, nur im Speicher halten
};

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.

Ein Seiten-Reload verliert die Journey nicht. Das Micro-Frontend merkt sich Warenkorb und Schritt lokal, lädt den Live-Warenkorb beim Mount vom Server nach und macht genau dort weiter, wo der Käufer aufgehört hat — auch wenn deine Seite bei jedem Laden einen frischen Session-Token mintet. Ist der Warenkorb serverseitig abgelaufen, startet die Journey einfach neu. Deine Seite muss dafür nichts tun.

Du willst stattdessen bewusst von vorn beginnen — ein echter "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.

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 minten, 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 minte 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 diesen Machine-to-Machine-Mint — 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 "@workspace/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 gemintet 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 = {
  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 mintest 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 mintet
    // 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.
    const res = await fetch("/api/shop/my-session", { method: "POST" });
    if (res.status === 401) return null;        // nicht eingeloggt -> im Warenkorb bleiben
    const { sessionToken } = (await res.json()) as { sessionToken: string };
    return sessionToken;
  },
};

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 "@workspace/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 — hier 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

In dieser Demo läuft das Minting über den Proxy unter den obigen Pfaden. In Produktion wird die Session im ADITUS-Core gemintet — der Vertrag ist identisch. Beide Aufrufe sind server-zu-server: Dein Backend authentifiziert sich mit dem Mint-Secret deines Clients (erzeugt in der ADITUS-Admin-Konsole) als Bearer-Token. Ein Mint pro Login ist das normale Muster; der Browser sieht ausschließlich den entstandenen Token.

Diesen exakten Ablauf kannst du mit deinen eigenen Zugangsdaten im Integrations-Tester ausprobieren — minten, mounten, Journey durchlaufen.

Session minten — Request

Session minten — Antwort (200)

Session widerrufen

DELETE /api/shop/session/:token mit demselben Bearer-Secret — es muss zum Client gehören, für den die Session gemintet wurde. Beim Logout aufrufen, damit der Token zusammen mit deiner eigenen Session stirbt. Antwort: { "revoked": true } (oder false, wenn die Session bereits abgelaufen war). Der Widerruf ist idempotent und kann fire-and-forget gesendet werden.

Fehler sind explizit