Definir el usuario y autenticación

La tecnología detrás del micro-frontend

La tienda de entradas ADITUS, entretejida en lugar de teletransportada. El micro-frontend renderiza el proceso de compra completo nativamente en tu página — sin iframe, sin cuerpo extraño visual. Está construido ligero y nativo al anfitrión, de modo que se ve y se siente como tu propio sitio, no como un widget incrustado.

Seguridad de pagos, PCI y CSP

La integración de componentes de terceros como las taquillas obliga tradicionalmente a un compromiso entre experiencia de usuario, rendimiento y seguridad informática. El micro-frontend resuelve ese conflicto con un paradigma híbrido: el flujo de interacción se renderiza en el light DOM nativo de tu página mientras que el paso de pago permanece estrictamente aislado — todo lo inofensivo ocurre en tu página, el pago en sí nunca.

En qué se diferencia de las alternativas del mercado

Los enfoques comparados

Cómo obtener el micro-frontend

El micro-frontend no está en el npm público ni en un CDN. Se entrega como paquete fuente directamente desde tu instancia ADITUS: TypeScript, ESM, totalmente tipado, sin ninguna dependencia de runtime propia — tu bundler (Vite, webpack, Next.js, Nuxt) lo compila junto con tu aplicación como tu propio código. El nombre de import en los snippets de esta página (@workspace/aditus-shop-embed) es el nombre de paquete de nuestra integración de referencia; el paquete descargable se llama @aditus/shop-embed — la API es idéntica.

Anfitriones SSR: Next.js y Nuxt

El micro-frontend es deliberadamente client-only. Su contenido está en vivo y ligado a la sesión — disponibilidad, precios y el carrito del usuario existen solo para una sesión autenticada en el momento de la petición, así que no hay nada significativo que un servidor anfitrión pudiera pre-renderizar. mount() crea una nueva raíz React del lado del cliente (createRoot); el marcado renderizado en el servidor dentro del contenedor no se hidrata. Eso hace que la integración SSR sea simple y predecible: renderiza un placeholder en el servidor, monta en el cliente y reserva el espacio para que nada salte.

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

El micro-frontend necesita una sesión

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 recarga de página no pierde el recorrido. El micro-frontend recuerda el carrito y el paso localmente, vuelve a cargar el carrito en vivo desde el servidor en el mount y continúa exactamente donde el usuario lo dejó — aunque tu página genere un nuevo token de sesión en cada carga. Si el carrito ha expirado en el servidor, el recorrido simplemente empieza de nuevo. Tu página no tiene que hacer nada para esto.

¿Prefieres un reinicio deliberado — un verdadero botón de «empezar de nuevo»? El paquete exporta clearJourney(): llámalo antes de montar (o volver a montar), y se descarta el registro de recorrido persistido localmente para la página actual, de modo que el siguiente mount arranca desde cero en el punto de entrada. Solo se elimina el puntero de reanudación local; cualquier estado de carrito en el servidor queda intacto.

Opcional: navegar de forma anónima, iniciar sesión en el pago

No tienes que saber de antemano quién es el usuario. Monta con una sesión de invitado y el micro-frontend permite a un visitante anónimo explorar eventos, elegir artículos y llenar el carrito. Solo cuando avanza más allá del carrito — hacia el registro y el pago — te pide definir el usuario real, mediante el callback onUserRequired. El resto del flujo continúa entonces con el carrito preservado.

1. 1

   Montar con una sesión de invitado

   Sigue siendo necesario un token de sesión para activar la tienda — pero puede ser una sesión de invitado: simplemente genérala SIN el campo email, sin necesidad de una dirección de marcador de posición. El visitante navega y llena el carrito bajo ella.

2. 2

   Salir del carrito activa onUserRequired

   En el momento en que el visitante avanza más allá del carrito, el micro-frontend llama a tu callback una vez y muestra un estado de espera neutro. Autentica al usuario (login/SSO), luego genera una nueva sesión ligada al usuario exactamente igual que la primera: servidor a servidor con tu secreto. La definición posterior del usuario también pasa por ese mint máquina a máquina — el secreto nunca llega al browser y el usuario nunca se define en el código cliente. Tu callback solo retransmite el token opaco resultante. Fundamental: tu backend deriva esa identidad de SU propia sesión autenticada (cookie/JWT); nunca debe aceptar el correo o el identificador de usuario desde el browser, o un visitante malicioso podría solicitar la sesión de otra persona y leer sus datos personales mediante el prellenado.

3. 3

   Devuelve el nuevo token — el carrito se conserva

   Devuelve el nuevo token de sesión y el micro-frontend lo adopta y liga al usuario identificado al carrito existente — el carrito, sus artículos y cualquier franja horaria se conservan sin cambios. Luego pasa al registro. Devuelve null para cancelar — el visitante simplemente permanece en el carrito, sin error.

4. 4

   Omitir onUserRequired para un usuario fijo

   Si omites el callback, nada cambia respecto al flujo clásico: monta con una sesión ligada a un usuario y el micro-frontend actúa como ese usuario desde el primer paso.

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);

Eventos GA4 / e-commerce (opcional)

El micro-frontend puede reportar el embudo de compra a tu analítica — pero solo si se lo pides. No incluye gtag, ni GTM, ni SDK de GA, no carga nada, no establece cookies y no envía nada por su cuenta. Añades un callback opcional, onEvent, y recibes eventos tipados ya formados según el esquema GA4 Enhanced Ecommerce de Google. Omite onEvent y nada cambia. Qué herramienta alimentas, y si tienes consentimiento para enviar, queda enteramente de tu lado.

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

Mantén los dos separados. Responden a preguntas diferentes y se emparejan, no son intercambiables.

Referencia de endpoints y respuestas

En esta demo, la generación pasa por el proxy en las rutas de arriba. En producción, la sesión se genera en el núcleo de ADITUS — el contrato es idéntico. Ambas llamadas son servidor a servidor: tu backend se autentica con el secreto de generación de tu cliente (generado en la consola de administración de ADITUS) como token Bearer. Una generación por inicio de sesión es el patrón normal; el browser nunca ve más que el token resultante.

Puedes probar este mismo flujo con tus propias credenciales en el probador de integración — generar, montar, recorrer el recorrido.

Generar una sesión — petición

Generar una sesión — respuesta (200)

Revocar una sesión

DELETE /api/shop/session/:token con el mismo secreto Bearer — el secreto debe pertenecer al cliente para el que se generó la sesión. Llámalo al cerrar sesión para que el token muera junto con tu propia sesión. Respuesta: { "revoked": true } (o false si la sesión ya había expirado). La revocación es idempotente y se puede enviar en fire-and-forget.

Los errores son explícitos