POST /v1/events

Tracker d'événements généraliste. Utilisez-le pour tout ce que vous voulez analyser et qui n'est pas une inscription :

• Vues de page
• Soumissions de formulaires lead
• Click-tracking sur landing pages
• Événements custom définis par le marchand

Si vos données ont une identité utilisateur significative (email/phone), utilisez plutôt /v1/signups — vous obtenez la dédup par utilisateur. /v1/events est pour le volume élevé sans identité.

Auth

Clé publique + HMAC. Même schéma que /v1/signups. Votre backend signe chaque appel.

Corps

{
  "name":       "lead_submitted",
  "properties": { "plan": "pro", "country": "DZ", "form": "footer" },
  "nonce":      "32-hex-single-use"
}

Champ	Type	Requis	Notes
name	string ≤ 64	✅	Nom d'événement. snake_case recommandé.
properties	object		Valeurs sérialisables JSON. Stockées telles quelles.
nonce	32-hex string	✅	Usage unique par clé, valable 1 h

name est aussi indexé pour un filtrage rapide. Restez sur un vocabulaire petit et stable — évitez de générer les noms dynamiquement (ex. viewed_product_42 est mauvais ; utilisez name="viewed_product" avec properties.product_id=42).

Réponse 202

{
  "data": { "status": "queued", "kind": "event", "store_id": 13 },
  "meta": { "request_id": "...", "api_version": "v1", "edge": true }
}

Même flow que les signups : mis en file en périphérie en ~30 ms, persisté à l'origine sous 5 s.

Dédup

Niveau unique : (store_id, nonce) UNIQUE. Pas de dédup par email. Si vous soumettez deux événements avec le même nonce, le second est enregistré comme status = 'duplicate' et ignoré. Sinon chaque appel compte.

Exemple : tracking de vues de page (Node.js, server-side)

import crypto from 'node:crypto';

export async function trackEvent(name, properties = {}) {
  const KEY_ID = process.env.DZ_PUBLIC_KEY;
  const SECRET = process.env.DZ_SIGNING_SECRET;
  const nonce = crypto.randomBytes(16).toString('hex');
  const ts    = Math.floor(Date.now() / 1000).toString();
  const body  = JSON.stringify({ name, properties, nonce });
  const hash  = crypto.createHash('sha256').update(body).digest('hex');
  const sig   = crypto.createHmac('sha256', SECRET).update(`${KEY_ID}\n${nonce}\n${ts}\n${hash}`).digest('hex');

  await fetch('https://api.dzbuild.app/v1/events', {
    method: 'POST',
    headers: {
      'Authorization': `DZ-Public ${KEY_ID}`,
      'X-DZ-Timestamp': ts, 'X-DZ-Nonce': nonce, 'X-DZ-Signature': sig,
      'Content-Type': 'application/json',
    },
    body,
  });
}

// Dans un middleware Express :
app.use((req, res, next) => {
  trackEvent('page_view', { path: req.path, ua: req.get('user-agent') }).catch(() => {});
  next();
});

Notez qu'on n'attend pas l'appel depuis le middleware page-view — fire-and-forget pour ne pas bloquer la requête utilisateur. La périphérie répond en ~30 ms de toute façon, mais ça protège contre les soucis réseau transitoires.

Ce qui compte dans votre quota

Chaque appel /v1/events réussi incrémente usage.event.total ET usage.event.billable. Pas de tier « lectures gratuites puis écritures facturables » ici — les events sont facturables dès la requête 1.

Si le volume monte, batchez côté vous : stockez dans votre propre queue et tirez un appel /v1/events par event logique en lots de 1 (pas de batch en v1 ; feature v1.1 pour la vraie télémétrie haut volume).

Erreurs

Mêmes que /v1/signups. Voir Erreurs.

Quand ne pas utiliser /v1/events

• Pour les commandes vitrine — elles passent par la vitrine et déclenchent order.created automatiquement. Ne doublez pas.
• Pour les événements server-internes non liés aux données marchand (CPU, hits cache). Utilisez un vrai APM.
• Pour les volumes massifs (>1M events/jour). Construisez votre pipeline analytique et exportez seulement les agrégats ici.