API de tracking (v1)

Événements, identification et création de leads avec la clé publique strk_.

L'API de tracking reçoit les événements de votre site et de vos applications, identifie vos visiteurs et crée des leads. Elle s'authentifie avec votre clé de tracking publique strk_…, disponible dès l'offre Starter, et c'est elle qu'utilise le SDK JavaScript.

Votre clé de tracking se trouve dans Engagement → Parcours, section Installer le tracking. Elle est publique et ne permet que l'écriture : elle peut figurer dans le code de votre site, mais ne donne accès à aucune donnée. Pour lire vos données ou agir depuis un serveur, utilisez l'API REST (clé secrète sk_live_, offres Pro et Enterprise) et son endpoint POST /events.

Principes

Utilisez l'API directement depuis votre serveur, une application mobile ou un outil d'automatisation. Toutes les requêtes sont en JSON et s'authentifient avec l'en-tête X-Strike-Key.

URL de base https://strikespace.net/api/v1
En-têtes Content-Type: application/json et X-Strike-Key: strk_…
Traitement Les endpoints de tracking valident la requête puis répondent 202 Accepted ; l'enregistrement se fait de façon asynchrone, en général en quelques secondes.
Débit 600 requêtes par minute et par clé. Au-delà, l'API répond 429 Too Many Requests : patientez avant de renvoyer.
CORS Les endpoints de tracking acceptent les appels depuis un navigateur.

Envoyer un événement

POST/api/v1/track
Champ Type Description
event_namerequis string 1 à 128 caractères : lettres, chiffres, espaces, _ . : -.
anonymous_id string Identifiant du visiteur non identifié (64 caractères max.). anonymous_id ou lead_id est requis.
lead_id uuid Identifiant STRIKE d'un lead de votre compte.
properties object Données libres de l'événement, 16 Ko maximum une fois sérialisées.
context object Contexte technique (page, campagne…). L'IP et le user-agent sont ajoutés par le serveur.
timestamp string Date ISO 8601 de l'action. Par défaut, l'heure de réception. Refusé s'il est plus de 24 h dans le futur.
message_id string Identifiant unique de l'événement (64 caractères max.), utilisé pour dédoublonner les renvois. Généré si absent.
curl
curl -X POST https://strikespace.net/api/v1/track \
  -H "Content-Type: application/json" \
  -H "X-Strike-Key: strk_votre_cle" \
  -d '{
    "event_name": "order_paid",
    "lead_id": "8f14e45f-ceea-4e7a-9a3b-2c1d5e6f7a80",
    "properties": { "amount": 25000, "currency": "XOF" },
    "message_id": "order-1042"
  }'
202 Événement accepté : { "success": true, "message_id": "order-1042" }
401 Clé absente ou invalide : { "error": "Clé de tracking (X-Strike-Key) invalide ou manquante." }
422 Requête invalide : champ mal formé (liste errors), ou { "error": "…" } si ni lead_id ni anonymous_id, propriétés > 16 Ko, ou horodatage invalide.

Envoyer un lot d'événements

POST/api/v1/batch

Envoie de 1 à 100 événements en une requête. Chaque élément de events suit le même format que /track. C'est l'endpoint utilisé par le SDK.

curl
curl -X POST https://strikespace.net/api/v1/batch \
  -H "Content-Type: application/json" \
  -H "X-Strike-Key: strk_votre_cle" \
  -d '{
    "events": [
      { "event_name": "page_view", "anonymous_id": "a1b2c3", "properties": { "path": "/offre" } },
      { "event_name": "checkout_started", "anonymous_id": "a1b2c3", "properties": { "cart_total": 25000 } }
    ]
  }'
202 { "success": true, "accepted": 2, "rejected": [] }. Les événements inutilisables sont listés dans rejected avec leur position (index) et la raison (error) ; les autres sont enregistrés.
401 Clé absente ou invalide.
422 events vide, plus de 100 éléments, ou un élément mal formé : le lot entier est refusé.

Identifier un visiteur

POST/api/v1/identify

Rattache un visiteur à un lead (existant ou nouveau) et met à jour ses informations. Au moins un champ parmi lead_id, email ou phone_number est requis.

Champ Type Description
lead_id uuid Lead existant de votre compte.
email string Adresse email valide (254 caractères max.), enregistrée en minuscules.
phone_number string Numéro de téléphone (32 caractères max.). Utilisez le format international : +229….
first_name string Prénom (120 caractères max.).
anonymous_id string Identifiant anonyme à relier à ce lead (voir Identité des leads).
traits object Attributs libres fusionnés dans les traits du lead, 16 Ko maximum.
message_id string Identifiant unique de l'appel (64 caractères max.).
curl
curl -X POST https://strikespace.net/api/v1/identify \
  -H "Content-Type: application/json" \
  -H "X-Strike-Key: strk_votre_cle" \
  -d '{
    "anonymous_id": "a1b2c3",
    "email": "awa@exemple.com",
    "first_name": "Awa",
    "traits": { "plan": "pro", "city": "Cotonou" }
  }'
202 { "success": true, "message_id": "…" }
401 Clé absente ou invalide.
422 Champ mal formé, aucun identifiant fourni, ou traits > 16 Ko.

Créer un lead

POST/api/v1/leads

Crée un lead dans votre compte et déclenche immédiatement son message de bienvenue. Utile pour connecter un formulaire externe ou un outil tiers. Le lead est compté dans votre quota mensuel.

Champ Type Description
first_namerequis string Prénom, 2 à 100 caractères.
phone_number string Format international strict, par exemple +22997000000. phone_number ou email est requis.
email string Adresse email valide.
country_code string Code pays ISO à 2 lettres. Par défaut BJ.
preferred_channel string whatsapp, email ou sms. Par défaut : WhatsApp dans la zone UEMOA, email ailleurs. Le canal doit être inclus dans votre offre.

Cet endpoint exige l'en-tête X-Strike-Key : le lead est rattaché au compte de la clé. Un éventuel champ user_id dans le corps de la requête est ignoré.

curl
curl -X POST https://strikespace.net/api/v1/leads \
  -H "Content-Type: application/json" \
  -H "X-Strike-Key: strk_votre_cle" \
  -d '{
    "first_name": "Kofi",
    "phone_number": "+22997000000",
    "country_code": "BJ",
    "preferred_channel": "whatsapp"
  }'
201 Lead créé : { "success": true, "data": { "id", "first_name", "preferred_channel", "status": "cold" } }
401 Clé absente ou invalide.
403 Quota mensuel de leads atteint, ou canal non inclus dans votre offre.
422 Champ invalide, ou ni téléphone ni email fourni.

Identité des leads

Un visiteur arrive d'abord anonymement sur votre site : le SDK lui attribue un anonymous_id stocké dans son navigateur, et tous ses événements y sont rattachés.

Lorsqu'un appel identify contient cet anonymous_id, STRIKE cherche le lead correspondant dans cet ordre :

  1. lead_id, s'il appartient à votre compte ;
  2. l'adresse email ;
  3. le numéro phone_number ;
  4. un lien déjà établi pour cet anonymous_id.

Si aucun lead n'est trouvé, un nouveau lead est créé, dans la limite de votre quota mensuel. L'identifiant anonyme est ensuite relié au lead : les événements passés du visiteur lui sont rattachés, ainsi que tous ses événements futurs.

  • Sur un lead existant, l'email et le téléphone ne sont complétés que s'ils étaient vides ; le prénom est mis à jour ; les traits sont fusionnés.
  • Un événement portant un lead_id qui n'appartient pas à votre compte est ignoré.
  • Appelez strike.reset() à la déconnexion pour qu'un autre utilisateur du même appareil ne soit pas confondu avec le précédent.

Bonnes pratiques & limites

100 événements maximum par appel à /batch
16 Ko pour properties ou traits, une fois sérialisés
128 caractères maximum pour un nom d'événement
600 / min requêtes par clé de tracking, au-delà : réponse 429
  • Nommez vos événements de façon stable, en snake_case et au passé ou à l'action : checkout_started, order_paid. Un segment se base sur le nom exact.
  • Fournissez un message_id côté serveur (identifiant de commande, de paiement…) : un même message_id n'est enregistré qu'une seule fois, vous pouvez donc renvoyer sans risque de doublon.
  • Préférez /batch dès que vous envoyez plusieurs événements à la fois.
  • Gérez les erreurs : une 4xx (hors 429) signale une requête à corriger, inutile de la renvoyer telle quelle ; une 5xx ou une 429 peut être renvoyée plus tard avec un délai croissant.
  • Identifiez le plus tôt possible, dès que le visiteur laisse un email ou un numéro : ses événements anonymes précédents lui seront rattachés.
  • N'envoyez pas de données sensibles (mots de passe, numéros de carte) dans properties ou traits.

Une question sur l'intégration ? Écrivez à contact@strike.app en indiquant l'endpoint, l'heure et le request_id de la réponse.