Intégration du SDK

Installation

Ajoutez le script de tracking Pomelo à votre site.

Note mode : Pomelo converge vers un modèle Strict par défaut / Extended par configuration. Le socle par défaut vise une mesure d’audience à collecte minimale. Les enrichissements d’acquisition, les événements plus riches et les traitements qui augmentent la collecte relèvent d’une configuration Extended explicite et documentée. Les vues par boutique, compte ou client sont une capacité d’organisation et d’accès, disponible selon le plan et la configuration.

La verification est optionnelle. Vous pouvez installer le script et commencer a collecter des donnees immediatement avec le siteId.

Quand vous creez le site dans le dashboard, entrez le hostname exact ou le script sera installe, par exemple app.example.com. Si vous voulez suivre le domaine complet et ses sous-domaines, confirmez ce perimetre pendant la creation du site.

Le dashboard vous donne une seule balise script à copier. Les surcharges d’endpoint sont réservées aux environnements internes ou avancés et ne font pas partie de l’installation par défaut.

Configuration runtime

Les réglages du site dans Pomelo sont la source d’autorité pour :

le profil de collecte actif (Strict ou Extended)
l’enregistrement de localhost
l’autocapture UI / formulaires / erreurs

La capture bornée d’actions UI/formulaires peut être activée en Strict. L’autocapture plus large, les labels auto-détectés et la capture d’erreurs requièrent une configuration explicitement compatible avec Extended ; le script limite la capture d’erreurs à Extended.

Au démarrage, le SDK récupère cette configuration runtime depuis Pomelo avec le site id présent dans la balise script. Si la configuration runtime ne peut pas être confirmée, le SDK utilise un fallback strict-safe. L’ingest serveur reste l’autorité finale dans tous les cas.

Un changement de profil dans Paramètres -> Sites -> Collecte n’agit que sur la collecte future. Il n’enrichit pas rétroactivement les événements passés.

Si vous migrez une installation plus ancienne, lisez d’abord le Guide de migration consommateurs.

Choisir le bon site dans Pomelo

Quand vous créez un site dans Pomelo, entrez toujours le hostname réel où le script sera installé.

Pomelo vous demande ensuite ce que vous voulez suivre :

Ce hostname uniquement
Le domaine et ses sous-domaines
Utilisez example.com ou www.example.com si vous voulez un seul site couvrant le domaine et ses sous-domaines.
Utilisez shop.example.com si vous voulez suivre ce sous-domaine comme un site distinct.
Sur une plateforme mutualisée comme tenant.wixsite.com, entrez le hostname exact, pas le domaine racine de la plateforme.

La vérification de propriété reste optionnelle et n’est affichée que quand Pomelo peut générer un challenge DNS valide pour ce périmètre.

Si le site reste en mode hostname exact, Pomelo continue de collecter normalement et affiche simplement que la vérification DNS n’est pas disponible pour ce type de site.

Pour une marketplace mono-hostname comme market.example.com/demo-shop, gardez un seul site pour le produit partage et utilisez tenantId / tenantSlug pour la boutique courante. Voir Analytics multi-tenant et le Guide multi-tenant.

Snippet recommandé

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

Copiez cette balise depuis le dashboard et collez-la dans le head de votre site. N’ajoutez pas de profil de collecte, d’autocapture ou de réglage tenant dans le snippet.

Par framework

Les exemples framework gardent le même contrat : charger analytics.js et passer uniquement l’id du site.

import type { ReactNode } from 'react';
import Script from 'next/script';

export default function RootLayout({
children,
}: {
children: ReactNode;
}) {
return (
  <html lang="fr">
    <body>
      {children}
      <Script
        id="pomelo-analytics"
        src="https://cdn.pomeloanalytics.com/latest/analytics.js"
        data-site-id="VOTRE_SITE_ID"
        strategy="afterInteractive"
      />
    </body>
  </html>
);
}

import { useEffect } from 'react';

function App() {
useEffect(() => {
const analytics = document.createElement('script');
analytics.src = 'https://cdn.pomeloanalytics.com/latest/analytics.js';
analytics.dataset.siteId = 'VOTRE_SITE_ID';
analytics.defer = true;
document.head.appendChild(analytics);

  return () => {
    analytics.remove();
  };

}, []);

return <>{/* votre app */}</>;
}

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

Référence des attributs HTML

`data-analytics-id`

Identifiant stable et sémantique pour les clics et formulaires. Devient el_id dans les événements. Combiné avec un scope, produit scope/id.

<a href="/signup" data-analytics-id="cta:hero_primary">Commencer</a>

Convention de nommage : minuscules, deux-points pour le namespacing (ex. cta:hero_primary, nav:pricing, form:contact).

Sanitisation : max 100 caractères, charset [a-zA-Z0-9_\-.:/ ] uniquement. Supprimé entièrement si des PII sont détectées.

`data-analytics-label`

Label explicite lisible pour un élément cliquable. À utiliser quand le label auto-détecté (texte, aria-label) est incorrect ou absent. Devient el_label avec el_label_src = "data".

<a
  href="/signup"
  data-analytics-id="cta:hero"
  data-analytics-label="Commencer gratuitement"
>
  <span class="icon">🚀</span> Commencer — c'est gratuit !
</a>

Sanitisation : max 80 caractères. Supprimé si des PII sont détectées.

`data-analytics-scope`

Regroupe des éléments liés sous un préfixe de section. Produit el_id = "scope/id" dans les événements.

<nav data-analytics-scope="nav">
  <a href="/pricing" data-analytics-id="pricing">Tarifs</a>
  <!-- el_id = "nav/pricing" -->
</nav>

Mêmes règles de sanitisation que data-analytics-id.

`data-analytics-ignore`

Exclut un sous-arbre de tout tracking (clics, formulaires). À utiliser sur les panneaux d’administration, barres de débogage ou zones sensibles.

<div data-analytics-ignore>
  <a href="/admin">Panneau admin</a>
  <!-- Ce clic ne sera PAS suivi -->
</div>

Exemples bons et mauvais

Identifiants (`data-analytics-id`)

Bon	Mauvais (rejeté par le SDK)
`cta:signup`	`user-alice@company.com` (email)
`nav:pricing`	`btn-550e8400-e29b-41d4-...` (UUID)
`form:contact`	`order-1234567890123` (chiffres longs)
`header:logo`	`a]b<c` (caractères non autorisés)
`checkout-step-2`	101+ caractères (dépassement)

Labels (`data-analytics-label`)

Bon	Mauvais (rejeté par le SDK)
`Ajouter au panier`	`Contact alice@example.com` (email)
`Télécharger le PDF`	`Appeler +33 6 12 34 56 78` (téléphone)

Scopes (`data-analytics-scope`)

Bon	Mauvais (rejeté par le SDK)
`header:nav`	`user:550e8400-...` (UUID)
`pricing`	`session:sk_live_abcdefg...` (token)

Guide de taggage

Utilisez des identifiants metier stables et tagguez l’element qui correspond exactement a l’interaction que vous voulez compter.

Ce que vous voulez mesurer	Ou ajouter le tag	Evenement emis	Filtre API
Clic sur un CTA interne	Element cliquable comme `<a>` ou `<button>`	`ui.click`	`action_family=instrumentation` + `action_key=instrumentation::...`
Clic vers un site externe	Element `<a>` sortant	`outbound.click`	`action_family=outbound` + `action_key=outbound::...`
Soumission validee d’un formulaire	Element `<form>`	`form.submit`	`action_family=forms` + `action_key=forms::...`

Clic sur un CTA interne

<a href="/demo" data-analytics-id="cta:hero_primary">Demander une demo</a>

Requete API :

curl -sS -G "https://api.pomeloanalytics.com/v1/reports/actions" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_123" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28" \
  --data-urlencode "action_family=instrumentation" \
  --data-urlencode "action_key=instrumentation::cta:hero_primary"

Clic sur un CTA sortant

<a
  href="https://partner.example/listing/123"
  data-analytics-id="partner:directory"
>
  Voir l'annonce
</a>

Requete API :

curl -sS -G "https://api.pomeloanalytics.com/v1/reports/actions" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_123" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28" \
  --data-urlencode "action_family=outbound" \
  --data-urlencode "action_key=outbound::partner:directory"

Soumission de formulaire

<form action="/api/demo" data-analytics-id="demo_request">
  <button type="submit">Demander une demo</button>
</form>

Requete API :

curl -sS -G "https://api.pomeloanalytics.com/v1/reports/actions" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_123" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28" \
  --data-urlencode "action_family=forms" \
  --data-urlencode "action_key=forms::demo_request"

Identifiants scopes

<section data-analytics-scope="hero">
  <a href="/demo" data-analytics-id="primary">Demander une demo</a>
</section>

Pomelo expose publiquement ce clic avec action_key=instrumentation::hero/primary.

Si vous voulez compter une soumission, tagguez le <form> lui-meme. Si vous voulez compter le clic avant soumission, tagguez l’element cliquable.

Pour les liens sortants, le tag data-analytics-id reste recommande pour un reporting stable par CTA. Sans tag explicite, Pomelo peut aussi compter le clic sortant quand vous interrogez action_family=outbound, et la reponse expose toujours les destinations groupees via top_targets, mais ce n’est plus le chemin principal pour les evenements taggues.

Cascade de détection des labels

Quand aucun data-analytics-label n’est défini, le SDK détecte un label automatiquement dans cet ordre :

Attribut data-analytics-label (el_label_src: "data")
Attribut aria-label (el_label_src: "aria")
Texte résolu via aria-labelledby (el_label_src: "aria")
Attribut title (el_label_src: "title")
Texte visible pour les boutons, liens, contrôles submit et éléments cliquables similaires — pas les inputs de formulaire libres ni les contentEditable (el_label_src: "text")
value pour <input type="submit"> ou <input type="button"> uniquement (el_label_src: "value")
alt pour les images (el_label_src: "text")

À l’intérieur d’un <form>, seuls les éléments submit et button sont éligibles à l’extraction de texte/valeur. Les éléments contentEditable sont ignorés.

Les labels auto-détectés sont en « best-effort » uniquement. Pour des analytics stables, préférez les attributs explicites :

data-analytics-id
data-analytics-label

Strict vs Extended dans le script

Le script ne décide pas seul du profil.

Strict conserve le socle borné de mesure d’audience.
En Strict, le sous-ensemble d’actions simples reste disponible pour des IDs stables et des destinations/paths bornés : ui.click, outbound.click, file.download, form.submit.
Extended débloque une collecte plus riche comme les paramètres d’acquisition, le contexte multi-tenant et une autocapture plus large quand ce comportement est activé pour le site.

Si un site est en Strict, les champs et événements Extended-only sont quand même filtrés une seconde fois côté ingest serveur, même si le client essaie de les envoyer.

Autrement dit, UTM, referrer complet, labels auto-détectés, erreurs, enrichissements tenant et custom events riches restent hors du socle Strict par défaut.

Ce sous-ensemble simple ne doit pas être lu comme une réouverture générale des actions. Il correspond uniquement à une couche agrégée et bornée d’actions simples, pas à une surface complète d’intelligence produit ou marketing.

`data-autocapture-labels-only` (défaut : `false`)

Cet attribut reste une restriction locale du script. Il ne peut pas activer une collecte Extended sur un site Strict.

Quand true :

ui.click ne se déclenche que pour les éléments avec un data-analytics-id explicite
Les clics détectés uniquement par auto-détection de label sont supprimés
el_label et el_label_src ne sont pas émis
el_role peut encore être émis quand disponible

Utilisez ce mode quand vous voulez un contrôle client plus strict sur les interactions UI émises.

Contrôles de snippet obsolètes

Ne vous appuyez plus sur des attributs de snippet comme data-autocapture-ui, data-autocapture-forms, data-autocapture-errors, data-capture-localhost ou data-allow-params comme source de vérité active. Le comportement autoritaire vient désormais de la configuration serveur du site.

Référence de sanitisation

Champ	Max	Si PII détecté	Si dépassement	Charset
`el_id`	100	Supprimé	Supprimé	`[a-zA-Z0-9_\-.:/ ]`
`el_scope`	100	Supprimé	Supprimé	Idem
`form_id`	100	Supprimé	Supprimé	Idem
`el_label`	80	Supprimé	Tronqué à 80	Tout (scanné)
`page_title`	200	Supprimé	Tronqué à 200	Tout (scanné)
`error.msg`	200	`[redacted]`	Tronqué à 200	Tout

Patterns PII détectés : adresses email, numéros de téléphone, UUID, séquences numériques longues (10+ chiffres consécutifs), chaînes de type token (20+ caractères alphanumériques).

Débogage

Activez le mode debug avec :

data-debug="true" sur la balise script
?pomelo_debug dans l’URL de la page

Les logs console affichent [pomelo] avec des informations de debug telles que les payloads en file d’attente, l’activité de flush et les détails d’initialisation. Un avertissement est affiché si la page n’est pas servie en HTTPS.

Intégration du SDK

Installation

Configuration runtime

Choisir le bon site dans Pomelo

Snippet recommandé

Par framework

Référence des attributs HTML

data-analytics-id

data-analytics-label

data-analytics-scope

data-analytics-ignore

Exemples bons et mauvais

Identifiants (data-analytics-id)

Labels (data-analytics-label)

Scopes (data-analytics-scope)

Guide de taggage

Clic sur un CTA interne

Clic sur un CTA sortant

Soumission de formulaire

Identifiants scopes

Cascade de détection des labels

Strict vs Extended dans le script

data-autocapture-labels-only (défaut : false)

Contrôles de snippet obsolètes

Référence de sanitisation

Débogage

`data-analytics-id`

`data-analytics-label`

`data-analytics-scope`

`data-analytics-ignore`

Identifiants (`data-analytics-id`)

Labels (`data-analytics-label`)

Scopes (`data-analytics-scope`)

`data-autocapture-labels-only` (défaut : `false`)