Definir o utilizador e a autenticação

A tecnologia por trás do micro-frontend

A bilhética ADITUS, integrada em vez de sobreposta. O micro-frontend apresenta nativamente na página todo o percurso de compra — sem iframe nem elementos visuais estranhos. Foi concebido para ser leve e nativo do host, para ter o aspeto e o comportamento do próprio site, e não de um widget incorporado.

Segurança dos pagamentos, PCI e CSP

A integração de componentes de terceiros, como sistemas de bilhética, obriga tradicionalmente a equilibrar a experiência do utilizador, o desempenho e a segurança informática. O micro-frontend resolve este conflito com um modelo híbrido: o fluxo de interação é apresentado no light DOM nativo da página, enquanto a etapa de pagamento permanece estritamente isolada — todas as operações não sensíveis decorrem na página; o pagamento nunca.

Como isso difere das alternativas de mercado

As abordagens comparadas

Como obter o micro-frontend

O micro-frontend não está disponível no npm público nem numa CDN. É fornecido como pacote de código-fonte diretamente pela sua instância ADITUS: TypeScript, ESM, totalmente tipado e sem dependências próprias em runtime. O seu bundler (Vite, webpack, Next.js ou Nuxt) compila-o juntamente com a sua aplicação, como se fosse código seu. O nome de importação nos excertos desta página (@workspace/aditus-shop-embed) corresponde ao pacote da nossa integração de referência; o pacote transferível chama-se @aditus/shop-embed — a API é idêntica.

Hosts SSR: Next.js e Nuxt

O micro-frontend é deliberadamente apenas para o cliente. O o respetivo conteúdo é ativo e vinculado à sessão — a disponibilidade, os preços e o carrinho do utilizador existem apenas para uma sessão autenticada no momento da pedido, portanto, não há nada significativo que um servidor host possa pré-apresentar. mount() cria uma nova raiz React do lado do cliente (createRoot); a marcação apresentada pelo servidor dentro do contêiner não é hidratada. Isso torna a integração SSR simples e previsível: apresente um placeholder no servidor, faça o mount no cliente e reserve o espaço 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 }} />;
}

O micro-frontend precisa de uma sessão

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.

Recarregar a página não elimina o percurso. O micro-frontend guarda localmente o carrinho e a etapa atual, volta a obter o carrinho em direto do servidor durante o mount e retoma exatamente no ponto em que o utilizador ficou — mesmo que a página crie um novo sessionToken em cada carregamento. Se o carrinho tiver expirado no servidor, o percurso recomeça. A página não precisa de efetuar qualquer ação adicional.

Se pretender começar deliberadamente de novo — com um verdadeiro botão «recomeçar» — o pacote exporta clearJourney(). Chame esta função antes do mount (ou de um novo mount) para eliminar o registo do percurso guardado localmente para a página atual; o mount seguinte começará de novo no ponto de entrada, em vez de retomar. Apenas é removido o ponteiro de retoma local; o estado do carrinho no servidor não é alterado.

Opcional: navegar anonimamente e iniciar sessão no checkout

Não é necessário conhecer antecipadamente a identidade do utilizador. Faça o mount com uma sessão de convidado e o micro-frontend permitirá a um visitante anónimo consultar eventos, escolher artigos e preencher o carrinho. Só quando avança para além do carrinho — em direção ao registo e ao checkout — é solicitado o utilizador real através do callback onUserRequired. O restante fluxo prossegue sem perder o carrinho.

1. 1

   Faça o mount com uma sessão de convidado

   Um token de sessão ainda é necessário para ativar a loja – mas pode ser uma sessão de convidado: basta criá-lo SEM o campo de email, sem necessidade de endereço fictício. O visitante navega e preenche o carrinho nessa sessão.

2. 2

   Deixar o carrinho aciona onUserRequired

   Quando o visitante avança para além do carrinho, o micro-frontend chama o callback uma vez e apresenta um estado neutro de espera. Autentique o utilizador (login/SSO) e crie uma nova sessão associada ao utilizador exatamente como a primeira: entre servidores, com o segredo. A identificação posterior do utilizador também é feita através deste mint machine-to-machine — o segredo nunca chega ao navegador e o utilizador nunca é definido no código do cliente. O callback apenas devolve o token opaco resultante. É essencial que o back-end obtenha esta identidade a partir da SUA própria sessão autenticada (cookie/JWT); nunca deve aceitar o email ou o ID do utilizador enviados pelo navegador, pois um visitante mal-intencionado poderia pedir a sessão de outra pessoa e aceder aos respetivos dados pessoais através do preenchimento automático.

3. 3

   Devolva o novo token – o carrinho continua

   Devolva o novo sessionToken e o micro-frontend substitui o anterior e associa o utilizador identificado ao carrinho existente — o carrinho, os artigos e quaisquer intervalos horários permanecem inalterados. Em seguida, avança para o registo. Devolva null para cancelar — o visitante permanece simplesmente no carrinho, sem erro.

4. 4

   Omitir onUserRequired para um utilizador fixo

   Se o utilizador deixar o callback de fora, nada muda em relação ao fluxo clássico: faça o mount com uma sessão vinculada ao utilizador e o microfrontend atua como esse utilizador desde a primeira etapa.

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/eventos de comércio eletrónico (opcional)

O micro-frontend pode comunicar o funil de compras ao sistema de analytics, mas apenas se essa opção for configurada. Não inclui gtag, GTM nem o SDK do GA, não carrega recursos, não define cookies e não envia dados autonomamente. Adicione o callback opcional onEvent para receber eventos tipados, já estruturados segundo o esquema Enhanced Ecommerce do GA4. Se omitir onEvent, nada muda. A ferramenta de destino e a validação do consentimento ficam inteiramente a cargo da integração.

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

Mantenha os dois separados. Eles respondem a perguntas diferentes e estão emparelhados, não intercambiáveis.

Referência de endpoint e resposta

Nesta demonstração, o mint é efetuado pelo proxy nos caminhos acima. Em produção, a sessão é criada no núcleo ADITUS — o contrato é idêntico. Ambas as chamadas são efetuadas entre servidores: o back-end autentica-se com o segredo mint do cliente (gerado na consola de administração ADITUS), utilizado como token Bearer. Um mint por login é o padrão habitual; o navegador vê apenas o token resultante.

Pode experimentar este fluxo exato com as suas próprias credenciais notestador de integração — criar a sessão, efetuar o mount e percorrer o fluxo.

Criar uma sessão — pedido

Criar uma sessão — resposta (200)

Revogar uma sessão

DELETE /api/shop/session/:token com o mesmo segredo Bearer — o segredo tem de pertencer ao cliente para o qual a sessão foi criada. Chame este endpoint ao terminar sessão para invalidar o token juntamente com a sessão do seu sistema. Resposta: { "revoked": true } (ou false se a sessão já tiver expirado). A revogação é idempotente e pode ser efetuada em modo fire-and-forget.

Erros são explícitos