Impostazione dell'utente e dell'autenticazione

La tecnologia dietro il micro-frontend

La biglietteria ADITUS, intessuta invece che teletrasportata. Il micro-frontend visualizza nativamente l'intero flusso di acquisto nella tua pagina: nessun iframe, nessun corpo estraneo visivo. È costruito in modo snello e nativo dell'host, quindi sembra e sembra il tuo sito, non un widget incorporato.

Sicurezza dei pagamenti, PCI e CSP

L’integrazione di componenti di terze parti come le biglietterie tradizionalmente impone un compromesso tra esperienza dell’utente, prestazioni e sicurezza IT. Il micro-frontend risolve questo conflitto con un paradigma ibrido: il flusso di interazione viene visualizzato nel DOM nativo della tua pagina mentre la fase di pagamento rimane strettamente isolata: tutto ciò che è innocuo accade nella tua pagina, il pagamento stesso non accade mai.

In cosa differisce dalle alternative del mercato

Gli approcci a confronto

Come si ottiene il micro-frontend

Il microfrontend non è su npm pubblico e non è su CDN. Viene fornito come pacchetto sorgente direttamente dalla tua istanza ADITUS: TypeScript, ESM, completamente tipizzato, con zero dipendenze runtime proprie: il tuo bundler (Vite, webpack, Next.js, Nuxt) lo compila insieme alla tua app come il tuo codice. Il nome di importazione negli snippet di questa pagina (@workspace/aditus-shop-embed) è il nome del pacchetto dalla nostra integrazione di riferimento; il pacchetto scaricabile si chiama @aditus/shop-embed — l'API è identica.

Host 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 un server host 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) — 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 }} />;
}

Il micro-frontend necessita di una sessione

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.

Una ricarica della pagina non perde il viaggio. Il micro-frontend ricorda il carrello e il passaggio localmente, recupera il carrello live dal server al momento del montaggio e continua esattamente da dove l'utente aveva interrotto, anche se la tua pagina conia un nuovo token di sessione ad ogni caricamento. Se il carrello è scaduto lato server, il viaggio ricomincia semplicemente da capo. La tua pagina non deve fare nulla per questo.

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.

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 coniarlo 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 conia 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 il conio machine-to-machine: 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 "@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/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 "@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 e sessionToken

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

Riferimento all'endpoint e alla risposta

In questa demo, il mint passa attraverso il proxy agli endpoint indicati sopra. In produzione la sessione viene generata nel core ADITUS, con lo stesso contratto. Entrambe le chiamate sono server-to-server: il backend si autentica con il mint secret del client, generato nella console di amministrazione ADITUS, come Bearer token. Una richiesta di mint per ogni login è il modello normale; il browser vede soltanto il token risultante.

Puoi provare questo flusso esatto con le tue credenziali nel filetester di integrazione — mint, mount e percorri il flusso.

Coniare una sessione: richiesta

Conia una sessione - risposta (200)

Revoca una sessione

DELETE /api/shop/session/:token con lo stesso segreto del portatore: il segreto deve appartenere al client per cui è stata coniata la sessione. Chiamalo al logout in modo che il token muoia con la tua sessione. Risposta: { "revocato": true } (o false se la sessione era già scaduta). La revoca è idempotente e sicura da licenziare e dimenticare.

Gli errori sono espliciti