Guide multi-tenant

Objectif

Note d’usage avance : ce guide décrit une restitution de statistiques par boutique, compte ou client. Le multi-tenant est un modele d’organisation et d’acces aux statistiques, pas un niveau de collecte par nature. Les exemples API requierent un plan ou l’API tenant est activee et une configuration compatible avec ce niveau de restitution.

Utiliser un seul site Pomelo pour le produit partage et un tenant_id stable pour chaque boutique, compte ou workspace.

Modele d’exemple :

Champ	Exemple
Hostname	market.example.com
site_id	site_marketplace
tenant_id	tenant_demo_shop
tenant_slug	demo-shop
tenant_name	Demo Shop

1. Garder un seul site pour le hostname partage

Si tous les tenants vivent sous un seul hostname, gardez un seul site Pomelo pour ce hostname. Ne creez pas un site par tenant sauf si chaque tenant a son propre hostname ou son propre domaine.

Installez d’abord le script Pomelo standard pour ce site :

<script
  defer
  src="https://cdn.pomeloanalytics.com/latest/analytics.js"
  data-site-id="site_marketplace"
></script>

2. Maintenir un registre tenant

Avant d’exposer des dashboards par tenant, synchronisez un registre tenant dans Pomelo depuis votre backend ou votre control plane.

Regles :

• tenant_id doit rester stable dans le temps
• tenant_slug peut changer quand le routage change
• tenant_name est une metadonnee d’affichage

3. Definir le tenant courant sur les pages tenant

Une fois le SDK charge, definissez le tenant actif une seule fois sur les pages tenant et laissez les evenements page, engagement, performance et erreur en heriter. Sur les pages tenant, ne chargez pas analytics.js deux fois : remplacez la balise standard de l’etape 1 par une seule balise avec contexte tenant, et definissez ce contexte depuis le callback onload de cette balise. Dans un framework, utilisez le callback equivalent indiquant que le SDK est pret. Pendant le demarrage du SDK, Pomelo applique ce contexte tenant avant de rejouer le premier pageview bufferise.

<script
  defer
  src="https://cdn.pomeloanalytics.com/latest/analytics.js"
  data-site-id="site_marketplace"
  onload="window.pomelo?.setTenant({
    tenantId: 'tenant_demo_shop',
    tenantSlug: 'demo-shop',
    tenantName: 'Demo Shop'
  })"
></script>

Quand l’utilisateur quitte le contexte tenant, effacez-le :

<script>
  window.pomelo?.clearTenant();
</script>

4. Utiliser les champs target tenant pour les actions cross-tenant

Depuis une page d’accueil partagee, une recherche ou un annuaire, attribuez une action a un tenant de maniere explicite :

window.pomelo?.track('shop.contact_click', {
  action_id: 'shop:contact_click',
  targetTenantId: 'tenant_demo_shop',
  targetTenantSlug: 'demo-shop',
  targetTenantName: 'Demo Shop',
});

Si un tenant explicite ne peut pas etre resolu, Pomelo laisse l’evenement en etat unresolved. Il ne le reassigne pas silencieusement depuis le path.

5. Requeter la vue globale et la vue tenant

Vue globale marketplace :

curl -sS -G "https://api.pomeloanalytics.com/v1/reports/overview" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_marketplace" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28"

Vue tenant :

curl -sS -G "https://api.pomeloanalytics.com/v1/reports/overview" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_marketplace" \
  --data-urlencode "tenant_id=tenant_demo_shop" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28"

Ventilation par tenant :

curl -sS -G "https://api.pomeloanalytics.com/v1/metrics/breakdown" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_marketplace" \
  --data-urlencode "dimension=tenant" \
  --data-urlencode "metric=pageviews"

Pour dimension=tenant, Pomelo retourne :

• key = tenant_id
• tenant_id comme identite canonique
• tenant_slug et tenant_name comme labels d’affichage courants du registre

6. Securiser l’acces du backoffice

Si un token est restreint avec allowedTenantIds, passez toujours tenant_id dans les requetes analytics. Le controle d’acces tenant est verifie sur tenant_id, pas sur le path ni sur tenant_slug.

Utilisez GET /v1/tenants?site_id=... pour lister les tenants actifs accessibles pour un site avant d’executer des requetes par boutique.

Checklist

• Utiliser un seul site_id partage par hostname partage
• Garder tenant_id stable et independant du routage
• Synchroniser le registre tenant avant d’exposer des dashboards tenant
• Utiliser setTenant() sur les pages tenant et targetTenant* sur les pages partagees
• Ne pas utiliser le filtre page comme frontiere de securite tenant
• Utiliser tenant_slug et tenant_name uniquement pour l’affichage