Intégrer la billetterie nativement

Démarrage rapide

Il existe deux façons d'obtenir une boutique fonctionnelle. Les deux utilisent le même script et le même élément ; elles diffèrent par l'entité qui crée la session.

Sans backend

L'élément crée lui-même une session navigateur pour votre publicKey, limitée aux domaines autorisés. Définissez cart-scope="tab" : sans identité serveur, la valeur par défaut "shared" aboutit à une erreur explicite. Chaque onglet a alors son propre panier. La session est anonyme : les visiteurs parcourent l'offre et remplissent le panier. Avant l'inscription, element.config.onUserRequired doit renvoyer un jeton de session lié à un utilisateur, émis par un serveur ; sinon la boutique s'arrête au panier avec un message.

<!-- Site without a backend: load the script once, place the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  cart-scope="tab"
></aditus-shop>

Avec backend

Votre serveur crée la session avec le mint secret et détermine qui est l'acheteur. Transmettez le token retourné à l'élément. Avec l'e-mail de l'acheteur, la valeur par défaut cart-scope "shared" conserve un seul panier dans tous les onglets.

// 1. On your server: create a session. The mint secret never leaves the server.
const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
    "Content-Type": "application/json",
  },
  // email comes from your own login session, never from the browser request.
  body: JSON.stringify({ publicKey: "pk_your_site", email: user.email }),
});
const { sessionToken } = await res.json();

<!-- 2. In your page: pass the token from your server to the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  session-token="SESSION_TOKEN_FROM_YOUR_SERVER"
></aditus-shop>

Remplacez pk_your_site par votre clé publique issue de l'admin ADITUS. developers.aditus.com est l'adresse de production du script et de l'API. Les deux façons sont détaillées plus bas.

La technologie derrière le micro-frontend

Le micro-frontend affiche tout le processus d'achat (événements, articles, panier, inscription, paiement, finalisation) dans le DOM de votre page. Il utilise la mise en page de votre page, et votre CSS peut styliser chacune de ses parties.

Votre site est de confiance : votre serveur authentifie l'utilisateur avant de générer une session identifiée. Le micro-frontend s'affiche volontairement dans le Light DOM de votre page, sans isolation iframe. Les scripts de votre page peuvent accéder au DOM et au stockage du navigateur ; sécurisez donc votre site et ses scripts tiers. L'autorisation d'origine par clé publique n'est pas une authentification de l'utilisateur. Les données de paiement sont saisies uniquement sur la page externe du prestataire de paiement.

Sécurité des paiements, PCI & CSP

La préparation de l'achat s'affiche dans votre page. Le paiement lui-même a lieu sur la page du prestataire de paiement : aucune donnée de paiement ne transite par votre page.

Comparaison avec l'iframe et le shadow DOM

Les approches comparées

Alternative : paquet source (distribué par vous)

Vous pouvez aussi télécharger le paquet source depuis votre instance ADITUS et l'intégrer à votre application (Vite, webpack, Next.js ou Nuxt). Vous gérez alors sa distribution : chaque mise à jour exige réinstallation, build et déploiement. Il n'est pas sur le npm public.

Applications SSR : Next.js & Nuxt

Le micro-frontend est délibérément client-only. Son contenu est en direct et lié à la session : disponibilités, prix et panier de l'utilisateur n'existent que pour une session authentifiée au moment de la requête, il n'y a donc rien de pertinent que votre serveur puisse pré-rendre. mount() crée une nouvelle racine React côté client (createRoot) ; le balisage rendu côté serveur à l'intérieur du conteneur n'est pas hydraté. Cela rend l'intégration SSR simple et prévisible : rendez un placeholder sur le serveur, montez sur le client et réservez l'espace pour que rien ne saute.

// Next.js (App Router): the micro-frontend is deliberately client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@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_your_site",
      sessionToken, // issued server-side, passed to the client component as a prop
      cartScope: "shared", // the default in frameworks too; trusted server identity
    });
    return () => handle(); // unmount on route change
  }, [sessionToken]);

  // Server and client render the SAME placeholder and so avoid a hydration mismatch.
  // min-height reserves the space so the page does not jump on mount (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

Le micro-frontend a besoin d'une session

import { mount } from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// Without a sessionToken the micro-frontend stays inactive: it only shows a
// neutral notice and starts no API calls: no cart, no registration,
// no checkout. Only a session activates the shop.
mount(el, {
  publicKey: "pk_your_site",
  // sessionToken missing -> the shop is not activated.
});

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

// getElementById can return null. Check it properly in TypeScript instead of using "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// AditusShopConfig types every option and gives you autocompletion.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",   // required as soon as a session is involved
  sessionToken,                // issued by your backend, keep it in memory only
  cartScope: "shared",          // default; requires a trusted server identity
};

const handle: ShopHandle = mount(el, config);

// The micro-frontend sends the X-Aditus-Session header with every shop call.
// On logout, revoke the session on the server and remount/update.

Au rechargement, un pointeur de parcours valide permet de demander le panier serveur sous la même portée autorisée et identité de confiance. Ce n'est pas une autorisation ni une garantie de reprise après expiration, effacement du stockage ou changement d'utilisateur. Le choix explicite tab ne fusionne pas les parcours des onglets ; shared par défaut maintient le verrou de checkout avec un seul écrivain.

Le retour de paiement utilise aditus-return (un token opaque, court et lié au serveur) avec aditus-pay. Il peut revenir dans le même onglet ou un nouveau, mais le serveur exige un client/une origine autorisés et l'identité de confiance correspondante. Les paramètres de retour ne prouvent pas un achat. Le serveur vérifie le paiement et finalise la tentative liée au token ; un résultat inconnu reste bloqué pour clarification, sans relance aveugle d'un nouvel achat. Les retours expirés ou non autorisés sont des erreurs explicites, pas une permission de créer une commande de remplacement.

L'attribution d'un prestataire prépare seulement le paiement : le récapitulatif reste modifiable. Le verrou commence lors de la redirection effective, après les consentements requis. Un paramètre de retour cancel/error ne prouve pas un échec : le backend revérifie le panier ; Completed avec order.id confirme la finalisation. Une nouvelle tentative exige la suppression réussie et confirmée de l'attribution pour ce même panier ; les résultats ambigus restent bloqués et peuvent être revérifiés. Cela ne garantit ni remboursement ni absence de règlement tardif.

Paiement par redirection : ce que votre page doit faire pour la session

• Servez l'URL de retour configurée avec l'embed monté. Préservez aditus-return et aditus-pay lors du routage ou des redirections de connexion nécessaires ; aditus-pay=success n'est jamais une autorisation. Fournissez une session valide pour la même identité de confiance et publicKey. Conservez cartScope et ne supprimez pas le parcours ni ne lancez un second checkout pour contourner un retour en attente, expiré ou incertain.

Vous préférez un redémarrage délibéré avec un véritable bouton « recommencer » ? Le paquet exporte clearJourney() : appelez-le avant de monter (ou remonter), et l'enregistrement de parcours persisté localement pour la page courante est supprimé, de sorte que le prochain mount démarre à neuf au point d'entrée. Seul le pointeur de reprise local est retiré ; tout état de panier côté serveur reste intact.

Point d'entrée : accueil, articles ou bon

Le point de départ est décidé par votre serveur lors de la création de la session, jamais par le navigateur. Sans eventSlug s'affiche l'aperçu des événements. Avec eventSlug, startMode choisit les articles (défaut), l'accueil ou le formulaire de bon ; assortment limite les articles.

La sélection d'articles et la suite après un bon suivent le parcours du magasin d'origine fondé sur les recommandations. Sans offre upsell utilisable ni vente complémentaire, on passe directement à la personnalisation des billets via les contrôles habituels de connexion/session ; avec une vente complémentaire, on affiche le panier. Une offre upsell utilisable ouvre d'abord son dialogue. Ignorer mène à la personnalisation sans vente complémentaire, ou au panier avec elle. Une mise à niveau confirmée mène au panier ; fermer le dialogue conserve la sélection. Le parcours n'enregistre jamais l'inscription en arrière-plan.

Les assortiments visibles peuvent avoir leur propre accès direct. Si un assortiment est fixé, l'accueil ne montre que son action billets, ni la liste complète ni l'action bon.

startMode: "home" ouvre l'accueil de l'événement. On y choisit Acheter des billets ou Échanger un bon ; l'ouverture seule ne crée aucun panier et n'échange aucun code. Acheter des billets ouvre la liste d'articles (limitée par assortment, si défini) ; Échanger un bon ouvre le formulaire de code. Sans eventSlug, la liste des événements apparaît d'abord, puis l'accueil de l'événement choisi. Un panier de bon préparé ou un parcours à reprendre reste prioritaire.

// Server side: use the same session route as above, only the body varies.
// You build user and your backend's login/session route yourself.
// eventSlug sets the event. startMode also works without a slug (event
// selection first, then the mode); only assortment needs the slug
// (otherwise 400 start_option_requires_event_slug).

// 1) Article start (default): the event's article selection
const bodyArticles = { publicKey, email: user.email, eventSlug: "ExperienceDaysv52024" };

// 2) Assortment start: only one assortment (id or exact name, case-insensitive)
const bodyAssortment = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  assortment: "Pressetickets",
};

// 3) Voucher start: "Redeem voucher / register ticket" first
const bodyVoucher = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  startMode: "voucher" as const,
};

const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify(bodyVoucher),
});
const { sessionToken }: { sessionToken: string } = await res.json();

/* Voucher form: the same tokens and role hooks as the rest of the journey */
.aditus-shop__voucher-panel  { /* panel around hints + form (general panel hook) */ }
.aditus-shop__voucher-hints  { /* the two hint lines */ }
.aditus-shop__voucher-form   { /* form */ }
.aditus-shop__voucher-input  { /* code field (also .aditus-shop__field-input) */ }
.aditus-shop__voucher-redeem { /* "Redeem" button (data-variant="primary") */ }
.aditus-shop__field-error    { /* rejection reason, role="alert" */ }
/* Event home page and event actions: structured expert hooks */
.aditus-shop__home             { /* home page; root data-step="home" */ }
.aditus-shop__home-info        { /* event information */ }
.aditus-shop__home-info-head   { /* heading and logo */ }
.aditus-shop__home-info-name   { /* event name */ }
.aditus-shop__home-info-date   { /* date */ }
.aditus-shop__home-info-venue  { /* venue */ }
.aditus-shop__home-info-desc   { /* description */ }
.aditus-shop__home-actions[data-variant="tiles"] { /* tiles, alternatively compact */ }
.aditus-shop__home-action[data-kind="articles"] { /* buy tickets; also home / voucher / assortment */ }
.aditus-shop__home-action-icon    { /* icon */ }
.aditus-shop__home-action-body    { /* text group */ }
.aditus-shop__home-action-title   { /* label */ }
.aditus-shop__home-action-desc    { /* optional description */ }
.aditus-shop__home-action-chevron { /* arrow */ }
/* Phase hook: [data-step="voucher"] on the root */

Liens de bon : échanger un code depuis l'URL

Les bons sont souvent envoyés sous forme de liens vers votre page avec le code en paramètre de requête, p. ex. …/tickets?code=ED24-ADITUS. Le micro-frontend peut reprendre ce code et l'échanger sans que le visiteur ne tape quoi que ce soit. Deux voies de transmission existent ; toutes deux aboutissent au même appel d'échange et se comportent ensuite de façon identique.

// Voucher links point to your site: https://your-site.com/tickets?code=ED24-ADITUS
// The route, request and authentication below are examples for your own website.
// The parameter name is up to you: here "code".

// Option A (browser): the micro-frontend reads the parameter itself.
import { mount } from "@aditus/shop-embed";

mount(document.getElementById("aditus-shop")!, {
  publicKey: "pk_your_site",
  sessionToken,                 // session with eventSlug (article or voucher start)
  voucherCodeParam: "code",     // read ?code=… once, remove it from the address bar, redeem it
});
// Web Component: <aditus-shop public-key="pk_your_site" voucher-code-param="code"></aditus-shop>

// Option B (server): your backend hands the code over when it creates the session.
// (Express example; the code never goes into the session response, only into the session context.)
app.get("/tickets", async (req, res) => {
  const code = typeof req.query.code === "string" ? req.query.code : undefined;
  const r = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: req.user?.email,
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher",       // or omit: article start, the code lands in the first cart
      voucherCode: code,          // undefined = normal start without a code
    }),
  });
  const { sessionToken }: { sessionToken: string } = await r.json();
  // The page additionally mounts with voucherCodeParam: "code" so that ?code= disappears
  // from the address bar (the session code wins, it is redeemed only once).
  res.render("tickets", { sessionToken });
});

Option : réserver le bon lors de la génération côté serveur

Si votre site veut traiter le refus avant d'ouvrir le micro-frontend, mettez redeemVoucherOnMint: true dans le POST /api/shop/session de confiance. Contrairement à la transmission normale du code, le serveur crée un panier pour l'utilisateur authentifié et y réserve réellement le bon avant de délivrer la session : ce n'est pas une requête de vérification supplémentaire. En cas de succès, ne transmettez que sessionToken au navigateur. Le micro-frontend reprend le même panier sans le recréer ni échanger le code deux fois, en mode voucher ou articles. Sans l'option, la transmission normale du voucherCode s'applique.

Ce mode exige voucherCode, un eventSlug fixé, un utilisateur identifié (email ; pas anonyme) et l'en-tête Idempotency-Key. Il est réservé au backend utilisant le secret de génération, pas à POST /shop/embed-session dans le navigateur. Seuls les codes de bon/billet sont pris en charge, pas PromotionCode. Le code est réservé dans un panier, mais le billet n'est pas encore inscrit ni délivré. L'inscription et la finalisation restent nécessaires ; des vérifications ultérieures peuvent encore échouer.

// Server side of your website: one voucher attempt, no additional check call.
// You implement the authentication and storage of this attempt yourself.
// attemptKey is a random id your backend stores durably per logical redemption
// attempt (e.g. crypto.randomUUID()). On network errors, resend the same id
// and the SAME body; never generate a new one before a retry.
async function prepareVoucherSession(
  user: { email: string },
  code: string,
  attemptKey: string,
) {
  const response = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
      "Content-Type": "application/json",
      "Idempotency-Key": attemptKey,
    },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: user.email, // only from your authenticated server session
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher", // or "articles"
      voucherCode: code,
      redeemVoucherOnMint: true,
    }),
  });
  const result: {
    sessionToken?: string; expiresAt?: number; voucherRedeemed?: boolean;
    error?: string; reason?: string; upstreamStatus?: number;
  } = await response.json();

  if (response.ok && result.sessionToken && result.voucherRedeemed === true) {
    // Only now pass it to the browser and mount the embed.
    return { sessionToken: result.sessionToken, expiresAt: result.expiresAt };
  }
  if (response.status === 422 && result.error === "voucher_rejected") {
    // Your own UI: handle the business rejection using reason, do not open the embed.
    // Translate only documented reason values into your own texts.
    return { rejected: result.reason };
  }
  if (response.status === 409 && result.error === "voucher_preparation_uncertain") {
    // Uncertain stays uncertain; a repeated POST never turns it into a success.
    // If the Shop API cannot provide the cart id, manual clarification is needed.
    throw new Error("Redemption uncertain; clarify with ADITUS, do not book again.");
  }
  if (response.status === 410 && result.error === "voucher_preparation_expired") {
    throw new Error("Prepared session no longer valid; no blind new session.");
  }
  // 400 = invalid request/key, 409 = conflict/attempt in progress,
  // 502/503 voucher_upstream_error = infrastructure, not a business error.
  throw new Error(`Session creation not completed (${response.status})`);
}

Le refus métier est 422 voucher_rejected avec un reason assaini : affichez-le sur votre site, sans monter le micro-frontend sans token. Une configuration/clé incorrecte vaut 400 ; 409 idempotency_conflict signifie une clé réutilisée avec d'autres données. Une opération en cours/incertaine, 502/503 ou un délai réseau n'indique pas un bon invalide. Conservez une clé aléatoire Idempotency-Key par tentative logique côté serveur et réessayez uniquement avec la même clé et exactement les mêmes données ; une réservation peut déjà exister. Ne journalisez ni code, ni email, ni erreurs brutes, ni token.

Une génération réussie peut laisser un panier réservé même si la page n'est jamais ouverte. Le nettoyage des paniers connus après refus/révocation est tenté au mieux ; un balayage au démarrage puis toutes les 60 secondes retente jusqu'à 25 dossiers par passage. La même clé et les mêmes données rejouent le résultat d'une tentative terminée encore valide. Si le token initial a expiré, a été révoqué, achevé, supprimé ou transféré, la réponse est 410 voucher_preparation_expired : ne recréez pas la réservation sans vérification. Un successeur autorisé peut prolonger/transférer la préparation au premier accès au panier. Supprimer l'URL n'annule pas le panier.

Erreurs exactes : 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (ou validation classique) ; 422 voucher_rejected contient reason et upstreamStatus, jamais le code ou message upstream brut. Motifs possibles : unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict signifie que les données ont changé ; voucher_preparation_pending renvoie Retry-After: 2 secondes et voucher_preparation_uncertain reste incertain même lors d'un nouvel essai (pas de succès automatique ultérieur). 410 voucher_preparation_expired interdit la reprise de la préparation initiale. 502/503 voucher_upstream_error est une erreur upstream. Si un panier a été créé sans retour de son identifiant, l'API disponible ne permet ni rapprochement ni libération automatique : l'état incertain est conservé et aucun second panier n'est créé lors du retry. Contactez ADITUS pour vérification manuelle avant toute nouvelle tentative. En cas d'échec de session-context, le micro-frontend affiche une erreur permettant de réessayer plutôt que de créer un panier.

Essayez les trois variantes en direct dans le Testeur d'intégration : générez une session avec eventSlug, choisissez startMode ou un assortiment, montez et observez le journal des requêtes. Le système de démonstration accepte le bon de test ED24-ADITUS sur ExperienceDaysv52024 (chaque échange réserve le billet environ 20 minutes ; revenir en arrière le libère). Ouvrir le Testeur d'intégration

Optionnel : naviguer anonymement, se connecter au paiement

Vous n'êtes pas obligé de savoir dès le départ qui est l'utilisateur. Montez avec une session invité et le micro-frontend laisse un visiteur anonyme parcourir les événements, choisir des articles et remplir le panier. Ce n'est que lorsqu'il dépasse le panier (vers l'inscription et le paiement) qu'il vous demande de définir l'utilisateur réel, via le callback onUserRequired. Le reste du flux continue ensuite avec le panier préservé.

1. 1

   Monter avec une session invité

   Un token de session reste nécessaire pour activer la boutique, mais ce peut être une session invité : générez-le simplement sans le champ email, aucune adresse fictive n'est nécessaire. Le visiteur navigue et remplit le panier sous cette session.

2. 2

   Quitter le panier déclenche onUserRequired

   Dès que le visiteur dépasse le panier, le micro-frontend appelle votre callback une seule fois et affiche un état d'attente neutre. Authentifiez l'utilisateur (login/SSO), puis générez une nouvelle session liée à l'utilisateur exactement comme la première : serveur à serveur avec votre secret. La définition ultérieure de l'utilisateur passe elle aussi par cette création de session de serveur à serveur. Le secret n'atteint jamais le navigateur et l'utilisateur n'est jamais défini dans le code client. Votre callback ne fait que relayer le token opaque obtenu. Point crucial : votre backend déduit cette identité de SA propre session authentifiée (cookie/JWT) ; il ne doit jamais accepter l'e-mail ou l'identifiant utilisateur depuis le navigateur, sinon un visiteur malveillant pourrait demander la session d'autrui et lire ses données personnelles via le préremplissage.

3. 3

   Renvoyez le nouveau token. Le panier est conservé

   Renvoyez le nouveau token de session et le micro-frontend l'adopte et lie l'utilisateur identifié au panier existant. Le panier, ses articles et d'éventuels créneaux horaires restent inchangés. Il passe ensuite à l'inscription. Renvoyez null pour annuler. Le visiteur reste simplement sur le panier, sans erreur.

4. 4

   Omettre onUserRequired pour un utilisateur fixe

   Si vous omettez le callback, rien ne change par rapport au flux classique : montez avec une session liée à un utilisateur et le micro-frontend agit comme cet utilisateur dès la toute première étape.

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// A guest session token is enough to mount: created server-to-server as
// usual, just without the email field (no placeholder address needed). The
// visitor may browse and fill the cart before a specific user is known.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",
  sessionToken: guestSessionToken,

  // Called once as soon as the visitor leaves the cart towards registration.
  // This is where you authenticate the user (login/SSO) and create a new,
  // user-bound session server-to-server.
  // Return the fresh token -> the micro-frontend adopts it and rebuilds the
  // cart under the identified user (articles are kept). Return null to
  // cancel -> the visitor stays in the cart, without an error.
  onUserRequired: async () => {
    // Calls only your backend, with no identity in the payload. Your backend reads
    // the signed-in user from its own session (cookie/JWT) and creates the session
    // server-side for exactly this identity. Never pass the email from the browser,
    // otherwise an attacker could insert someone else's address here and reach
    // that person's personal data through the prefill.
    // host.loginAndMintSession(): Promise<string | null> is your own function.
    // Implement login/SSO + authenticated backend call + server-side session creation on your website.
    // On cancel the function returns null; on failure it throws explicitly.
    return host.loginAndMintSession();
  },
};

const handle: ShopHandle = mount(el, config);

Événements GA4 / e-commerce (optionnel)

Le micro-frontend peut remonter le tunnel d'achat vers votre analytique, mais seulement si vous le lui demandez. Il n'embarque ni gtag, ni GTM, ni SDK GA, ne charge rien, ne pose aucun cookie et n'envoie rien de lui-même. Vous ajoutez un callback optionnel, onEvent, et recevez des événements typés déjà formatés selon le schéma GA4 Enhanced Ecommerce de Google. Omettez onEvent et rien ne change. Quel outil vous alimentez, et si vous avez le consentement pour envoyer, reste entièrement de votre côté.

import {
  mount,
  type ShopHandle,
  type ShopAnalyticsEvent,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_your_site",
  sessionToken,
  // Optional. If you leave out onEvent, nothing changes: the micro-frontend
  // sends nothing, loads no gtag/GTM/GA SDK and sets no cookies.
  // Tool, consent and mapping stay entirely with you. This example uses GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent is yours: only send once the user has agreed.
    if (!hasAnalyticsConsent()) return;
    // The events already follow the GA4 schema (name + items/value/currency ...),
    // so pass them to gtag 1:1.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey vs. sessionToken

Gardez les deux distincts. Ils répondent à des questions différentes et sont appariés, non interchangeables.

Référence des endpoints & réponses

Les deux appels proviennent de votre backend : il s'authentifie avec le mint secret de votre client (généré dans la console d'administration ADITUS) comme token Bearer. Une session par connexion est le schéma habituel ; le navigateur ne voit que le token obtenu. Les sites sans backend n'utilisent pas ces endpoints : l'élément crée lui-même sa session navigateur via POST /api/shop/embed-session, limité au domaine (public-key avec cart-scope="tab").

Vous pouvez essayer ce flux exact avec vos propres identifiants dans le testeur d'intégration. Générez une session, montez la boutique et suivez le parcours.

Générer une session : requête

Générer une session : réponse (200)

Révoquer une session

DELETE /api/shop/session/:token avec le même secret Bearer. Le secret doit appartenir au client pour lequel la session a été générée. Appelez-le à la déconnexion afin que le token meure avec votre propre session. Réponse : { "revoked": true } (ou false si la session avait déjà expiré). La révocation est idempotente et peut être envoyée en fire-and-forget.

Lectures serveur à serveur

Un backend qui pilote le micro-frontend (coque de kiosque, boutique sur site) a généralement besoin de données du tenant avant de générer une session : quels événements existent et sont en vente, quelles langues parle le shop, quelles listes de référence et quel branding s'appliquent. Quatre endpoints de lecture y répondent avec les mêmes identifiants que la génération (secret Bearer + en-tête X-Aditus-Public-Key, même limite de débit, Cache-Control: no-store). Ce sont des projections filtrées de la Shop API, jamais un relais brut ; ?language= (ou Accept-Language, de par défaut) choisit la langue des noms. Erreurs : 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Les erreurs sont explicites