Contrat HTTP

Le contrat entre la librairie et la plateforme est public et stable: n'importe qui peut l'appeler à la main, et toute évolution incompatible imposerait une nouvelle version de chemin.

POST /api/collect

POST https://sarutobi.ascencia.re/api/collect
Content-Type: text/plain;charset=UTF-8
Origin: https://exemple.fr

{
  "k": "st_live_8f3a1c9d2e4b6071",
  "a": "anon_7f2...",
  "d": "user_42",
  "s": "sess_b81...",
  "rel": "[email protected]",
  "env": "production",
  "c": { "locale": "fr" },
  "b": [
    { "i": "evt_01...", "t": "pageview", "u": "https://exemple.fr/builds", "r": "https://reddit.com/", "w": 1920, "ts": 1785312000000 }
  ]
}

text/plainest volontaire : ce type est « simple » au sens CORS, donc aucune requête de pré-vol n'est déclenchée pour chaque envoi. Le corps reste du JSON. application/json est accepté aussi, pour les appels serveur à serveur qui se moquent du pré-vol.

Enveloppe

k — clé publique du site. Requis.
b — de 1 à 20 events. Requis.
c — contexte, fusionné dans les propriétés de chaque event du lot.
a, d, s — identité anonyme, identité métier et session.
rel, env — release et environnement instrumentés.

Event

i — identifiant opaque utilisé pour rendre les retries idempotents.
t — pageview, pageleave, custom, vital ou error. Requis.
u — URL absolue de la page. Requis.
ts — horodatage client en millisecondes. Requis.
r— referrer. Ignoré s'il pointe vers le même hôte.
w— largeur d'écran, convertie serveur en classe d'écran.
n — nom, requis pour custom, vital et error.
p — propriétés (custom uniquement), d — durée (pageleave), v — valeur (vital), st — pile (error).

Le client envoie les identifiants Product Analytics mais jamais le pays, l'appareil, le système ou le navigateur. Ces dimensions restent dérivées côté serveur. Un champ de ce genre présent dans un event est ignoré.

Réponses

202 — accepté, y compris si tout le lot a été filtré.
400 — JSON invalide ou enveloppe non conforme.
401 — clé inconnue ou site archivé.
403 — origine absente de la liste des domaines autorisés.
413 — corps au-delà de 32 ko.
429 — quota dépassé, avec un en-tête Retry-After.

Le corps de réponse est toujours vide. L'endpoint est public : il ne doit rien apprendre à qui le sonde. Le mode debug de la librairie affiche le code HTTP, ce qui suffit à diagnostiquer.

Un event invalide au sein d'un lot valide est rejeté seul, les autres sont insérés, et la réponse reste 202. Perdre vingt events parce qu'un seul a un nom trop long serait absurde.

Tester à la main

terminal

curl -X POST https://sarutobi.ascencia.re/api/collect \
  -H 'Content-Type: application/json' \
  -d '{"k":"st_live_8f3a1c9d2e4b6071","b":[{"t":"custom","n":"test_manuel",
       "u":"https://exemple.fr/","ts":'"$(date +%s000)"'}]}' -i

Attendu : 202, et l'event visible dans le compteur temps réel du dashboard sous cinq secondes.