Setting the user & authentication

The technology behind the micro-frontend

The ADITUS ticketshop, woven in instead of teleported. The micro-frontend renders the complete purchase flow natively into your page — no iframe, no visual foreign body. It is built lean and host-native, so it looks and feels like your own site, not an embedded widget.

Payment security, PCI & CSP

Integrating third-party components such as ticketshops traditionally forces a trade-off between user experience, performance and IT security. The micro-frontend resolves that conflict with a hybrid paradigm: the interaction flow renders in the native light DOM of your page while the payment step stays strictly isolated — everything harmless happens in your page, the payment itself never does.

How it differs from the market alternatives

The approaches compared

How you obtain the micro-frontend

The micro-frontend is not on public npm and not on a CDN. It is delivered as a source package straight from your ADITUS instance: TypeScript, ESM, fully typed, with zero runtime dependencies of its own — your bundler (Vite, webpack, Next.js, Nuxt) compiles it together with your app like your own code. The import name in the snippets on this page (@workspace/aditus-shop-embed) is the package name from our reference integration; the downloadable package is named @aditus/shop-embed — the API is identical.

SSR hosts: Next.js & Nuxt

The micro-frontend is deliberately client-only. Its content is live and session-bound — availability, prices and the user's cart exist only for an authenticated session at request time, so there is nothing meaningful a host server could pre-render. mount() creates a fresh client-side React root (createRoot); server-rendered markup inside the container is not hydrated. That makes SSR integration simple and predictable: render a placeholder on the server, mount on the client, and reserve the space so nothing jumps.

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

The micro-frontend needs a 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.

A page reload does not lose the journey. The micro-frontend remembers cart and step locally, re-fetches the live cart from the server on mount and continues exactly where the user left off — even though your page mints a fresh session token on every load. If the cart has expired server-side, the journey simply starts fresh. Your page does not have to do anything for this.

Want a deliberate fresh start instead — a real "start over" button? The package exports clearJourney(): call it before mounting (or re-mounting) and the locally persisted journey record for the current page is dropped, so the next mount starts fresh at the entry point. Only the local resume pointer is removed; any server-side cart state is untouched.

Optional: browse anonymously, sign in at checkout

You do not have to know who the user is up front. Mount with a guest session and the micro-frontend lets an anonymous visitor browse events, pick articles and fill the cart. Only when they move past the cart — toward registration and checkout — does it ask you to establish the real user, via the onUserRequired callback. The rest of the flow then continues with the cart preserved.

1. 1

   Mount with a guest session

   A session token is still required to activate the shop — but it can be a guest session: simply mint it WITHOUT the email field, no placeholder address needed. The visitor browses and fills the cart under it.

2. 2

   Leaving the cart triggers onUserRequired

   The moment the visitor advances past the cart, the micro-frontend calls your callback once and shows a neutral pending state. Authenticate the user (login/SSO), then mint a fresh, user-bound session the exact same way as the first one: server-to-server with your secret. The later user is established via that machine-to-machine mint too — the secret never reaches the browser and the user is never set in client code. Your callback only relays the resulting opaque token. Crucially, your backend derives that identity from its OWN authenticated session (cookie/JWT); it must never accept the email or user id from the browser, or a malicious visitor could request someone else's session and read their personal data via the prefill.

3. 3

   Return the new token — the cart carries over

   Return the fresh session token and the micro-frontend swaps it in and binds the identified user to the existing cart — the cart, its articles and any timeslots survive unchanged. Then it enters registration. Return null to abort — the visitor simply stays on the cart, no error.

4. 4

   Omit onUserRequired for a fixed user

   If you leave the callback out, nothing changes from the classic flow: mount with a user-bound session and the micro-frontend acts as that user from the very first step.

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)

The micro-frontend can report the shopping funnel to your analytics — but only if you ask it to. It bundles no gtag, no GTM and no GA SDK, loads nothing, sets no cookies and sends nothing on its own. You add one optional callback, onEvent, and receive typed events already shaped in Google's GA4 Enhanced-Ecommerce schema. Omit onEvent and nothing changes. Which tool you feed, and whether you have consent to send, stays entirely on your side.

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

Keep the two separate. They answer different questions and are paired, not interchangeable.

Endpoint & response reference

In this demo, minting runs through the proxy at the paths above. In production the session is minted in the ADITUS core — the contract is identical. Both calls are server-to-server: your backend authenticates with your client's mint secret (generated in the ADITUS admin console) as a Bearer token. One mint per login is the normal pattern; the resulting token is all the browser ever sees.

You can try this exact flow with your own credentials in the integration tester — mint, mount, walk the journey.

Mint a session — request

Mint a session — response (200)

Revoke a session

DELETE /api/shop/session/:token with the same Bearer secret — the secret must belong to the client the session was minted for. Call it on logout so the token dies with your own session. Response: { "revoked": true } (or false if the session had already expired). Revoking is idempotent and safe to fire-and-forget.

Errors are explicit