Aller au contenu
Pomelo Analytics

Demarrage rapide

1. Creer un token

Section intitulée « 1. Creer un token »

Note mode : les exemples API et tenant de cette page peuvent reposer sur des donnees relevant d’une configuration Extended explicite. Le socle par défaut visé reste une mesure d’audience plus stricte.

Voir aussi : Strict, Extended et rapports mixtes et le Guide de migration consommateurs.

Allez dans Dashboard > Parametres > Acces API et creez un nouveau token.

  • Choisissez un scope : metrics:read (acces lecture, toujours borne par le plan) ou usage:read (usage uniquement)
  • Vous pouvez restreindre l’acces a des sites specifiques via l’allowlist
  • Si la politique API active autorise l’acces tenant, vous pouvez aussi restreindre l’acces a des boutiques specifiques via allowedTenantIds
  • Copiez le secret immediatement — il n’est affiche qu’une seule fois

La verification est optionnelle et ne bloque pas la collecte. Vous pouvez commencer a tracker des que le script est installe et que l’identifiant du site est configure.

Lors de la creation d’un site dans le dashboard, entrez le hostname reel ou le script sera installe. Pomelo vous demande ensuite de confirmer le perimetre de suivi :

  • Ce hostname uniquement
  • Le domaine et ses sous-domaines

Si le hostname appartient a une plateforme mutualisee ou a un suffixe prive comme tenant.github.io ou tenant.wixsite.com, Pomelo garde le site en mode hostname exact. La collecte commence des que le script est installe ; la verification DNS reste optionnelle et ne concerne que les sites larges.

2. Premier appel

Section intitulée « 2. Premier appel »
Fenêtre de terminal
curl -sS \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  -H "X-Request-Id: my-request-123" \
  "https://api.pomeloanalytics.com/v1/me"

3. Requeter des metriques

Section intitulée « 3. Requeter des metriques »

Pour une marketplace ou une app multi-tenant, ajoutez tenant_id quand la politique API active autorise l’acces tenant-scope et que vous voulez une vue boutique. Utilisez site_id seul pour la vue globale marketplace. Voir Analytics multi-tenant et le Guide multi-tenant.

Quand vous requetez dimension=tenant, Pomelo retourne le tenant_id stable dans la cle key. Utilisez tenant_slug et tenant_name uniquement pour l’affichage.

Les reponses analytics profile-aware exposent aussi un objet availability. Utilisez-le comme autorite backend pour la classe de route, la couverture partielle apres collection_profile_effective_at et la non-retroactivite de l’historique Extended.

  • Strict-safe : timeseries standard, breakdown standard, content
  • Mixed : overview, acquisition, actions
  • Advanced / gated : goals/conversions, timeseries tenant-scope, breakdowns tenant. Ces lectures dependent du plan, de l’acces API tenant et de la configuration compatible.

Sur les routes mixtes, Strict retourne encore une lecture utile pour le sous-ensemble strict-safe :

  • overview : KPIs audience, top pages, aperçu acquisition-lite
  • acquisition : canaux, referrers host-only, landing pages
  • actions : actions simples tagguées (ui.click, outbound.click, file.download, form.submit)

Lisez une route mixte comme un rapport avec un noyau strict-safe et des sections Extended clairement signalées. Si vous êtes en Strict, les sections non marquées constituent la lecture complète du socle de base. Utilisez availability.readModel pour identifier ce socle, puis availability.sections pour repérer les parties qui relèvent encore d’une acquisition enrichie ou d’actions avancées.

Le même modèle de lecture vaut aussi dans le dashboard :

  • Overview reste utile en Strict avec ses KPIs, ses top pages et son aperçu acquisition-lite
  • Audience reste utile en Strict pour appareil, navigateur, OS, langue et pays
  • Acquisition et Actions restent mixtes car seul leur sous-ensemble lite/simple appartient au socle par défaut
Fenêtre de terminal
curl -sS \
-G "https://api.pomeloanalytics.com/v1/metrics/timeseries" \
-H "Authorization: Bearer $POMELO_API_TOKEN" \
--data-urlencode "site_id=site_123" \
--data-urlencode "metric=pageviews" \
--data-urlencode "from=2026-02-01" \
--data-urlencode "to=2026-02-28" \
--data-urlencode "interval=day"

4. Requeter des CTA et formulaires exacts

Section intitulée « 4. Requeter des CTA et formulaires exacts »

Note plan : /v1/reports/actions et les endpoints objectifs dépendent de la politique API active. /v1/reports/actions est maintenant une famille de routes mixte : le sous-ensemble strict-safe fonctionne en Strict, mais les familles avancées dépendent toujours d’Extended.

Si le site sélectionné ou la période demandée ne contient pas de données Extended compatibles pour une famille Extended-only, Pomelo retourne HTTP 409. Les routes mixtes restent en 200, exposent leur socle via availability.readModel et exposent les verrous de section via availability.sections.

Utilisez GET /v1/reports/actions quand vous voulez recuperer des comptes exacts sur des clics UI taggues, des clics sortants, des téléchargements et des soumissions de formulaire.

Fenêtre de terminal
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"

Utilisez action_key pour les requetes exactes sur l’API publique. Si vous ajoutez un parent data-analytics-scope, Pomelo derive l’identifiant compose dans cette cle, par exemple instrumentation::hero/primary.

Si vous voulez aller au-dela d’une action tagguee exacte, recuperez la famille seule via action_family=outbound. La reponse contient alors top_targets, qui resume les destinations sortantes.

Les familles plus riches comme errors, custom et les lectures derivees de goals restent hors du socle Strict par defaut.

Autrement dit, Strict couvre une couche simple d’actions agrégées, pas une surface complète d’intelligence d’actions. UTM, campagnes, goals, contexte tenant avancé et payloads custom plus riches ne reviennent pas dans le socle par défaut.

Voir Intégration du SDK pour les regles de taggage HTML qui produisent ces dimensions.

5. Utiliser les filtres

Section intitulée « 5. Utiliser les filtres »

Passez un objet JSON dans le parametre filters pour affiner les resultats :

Fenêtre de terminal
curl -sS \
  -G "https://api.pomeloanalytics.com/v1/metrics/timeseries" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_123" \
  --data-urlencode "metric=pageviews" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28" \
  --data-urlencode 'filters={"device":"mobile","referrer":"google.com"}'

Cles de filtre disponibles : device, referrer, page, browser, os.

6. Headers de reponse

Section intitulée « 6. Headers de reponse »

Chaque reponse inclut ces headers :

HeaderDescription
X-Request-IdIdentifiant unique de la requete — a inclure dans les demandes de support
X-RateLimit-LimitNombre maximum de requetes autorisees dans la fenetre courante
X-RateLimit-RemainingRequetes restantes avant limitation
X-RateLimit-ResetTimestamp Unix de reinitialisation de la fenetre

Etapes suivantes

Section intitulée « Etapes suivantes »