Le suivi côté serveur est la méthode recommandée pour le suivi des conversions car il :
- ✅ Ne peut pas être bloqué par les bloqueurs de publicités
- ✅ Garantit la livraison des événements de tracking
- ✅ Confirme les actions avant le tracking (ex: paiement vérifié)
- ✅ Fonctionne avec les webhooks des fournisseurs de paiement
Prérequis
Important : Pour que le suivi des conversions fonctionne, les utilisateurs
doivent arriver sur votre site via un deeplink Taapit. C’est ainsi que
l’ID de suivi (ta_tid) est généré et transmis à votre site.
Avant de commencer :
- Créez un deeplink Taapit pointant vers votre site ou landing page
- Activez le suivi des conversions sur votre lien :
- Allez dans les paramètres de votre lien dans le dashboard Taapit
- Activez Suivi des conversions
- Obtenez votre Secret Key depuis Paramètres → Conversion dans votre dashboard Taapit
N’exposez jamais votre clé secrète dans le code côté client. Utilisez-la
uniquement sur votre serveur.
Installation
Même pour le suivi côté serveur, vous devez installer le SDK sur votre
frontend pour capturer le cookie ta_tid.
Étape 1 : Frontend - Installer le SDK
Ajoutez le composant Analytics pour capturer le ta_tid :import { Analytics } from "taapit-sdk/react";
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics />
</body>
</html>
);
}
TAAPIT_API_KEY=taapit_sk_xxx
N’exposez jamais votre clé API secrète dans le code côté client.
Étape 3 : Backend - Suivre les conversions
import { Taapit } from "taapit-sdk";
import { cookies } from "next/headers";
const taapit = new Taapit({
apiKey: process.env.TAAPIT_API_KEY,
});
export async function POST(request: Request) {
const body = await request.json();
// Obtenir l'ID de suivi depuis le cookie
const cookieStore = cookies();
const trackingId = cookieStore.get("ta_tid")?.value;
// Créer l'utilisateur dans votre base de données
const user = await db.users.create({
email: body.email,
name: body.name,
});
// Suivre le lead
if (trackingId) {
await taapit.track.lead({
trackingId,
customer: {
externalId: user.id,
email: user.email,
},
});
}
return Response.json({ user });
}
Étape 1 : Frontend - Ajouter le script
<script src="https://taap.it/api/sdk"></script>
Étape 2 : Frontend - Envoyer l’ID de suivi au backend
<script>
document
.getElementById("signup-form")
.addEventListener("submit", async (e) => {
e.preventDefault();
const formData = new FormData(e.target);
// Inclure l'ID de suivi dans la requête
await fetch("/api/signup", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: formData.get("email"),
name: formData.get("name"),
trackingId: taapit.getTrackingId(), // Inclure ceci !
}),
});
});
</script>
Étape 3 : Backend - Appeler l’API REST
curl -X POST https://track.taap.it/api/events/lead \
-H "Authorization: Bearer taapit_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"trackingId": "rLnWe1uz9t282v7g",
"customer": {
"externalId": "user_123",
"email": "[email protected]"
}
}'
Suivre un Lead
SDK Node.js
Python
PHP
Ruby
Go
import { Taapit } from 'taapit-sdk';
import { cookies } from 'next/headers';
const taapit = new Taapit({ apiKey: process.env.TAAPIT_API_KEY });
export async function POST(request: Request) {
const body = await request.json();
const cookieStore = cookies();
const trackingId = cookieStore.get('ta_tid')?.value || body.trackingId;
// Créer l'utilisateur
const user = await createUser(body);
// Suivre le lead
if (trackingId) {
const result = await taapit.track.lead({
trackingId,
customer: {
externalId: user.id,
email: user.email,
firstname: body.firstName,
lastname: body.lastName,
},
metadata: {
source: 'signup-api',
plan: body.plan,
},
});
if (!result.success) {
console.error('Échec du suivi du lead:', result.error);
}
}
return Response.json({ user });
}
import requests
def track_lead(tracking_id: str, user: dict):
response = requests.post(
'https://track.taap.it/api/events/lead',
headers={
'Authorization': f'Bearer {TAAPIT_API_KEY}',
'Content-Type': 'application/json',
},
json={
'trackingId': tracking_id,
'customer': {
'externalId': user['id'],
'email': user['email'],
},
},
)
return response.json()
<?php
function trackLead($trackingId, $user) {
$ch = curl_init('https://track.taap.it/api/events/lead');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . TAAPIT_API_KEY,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'trackingId' => $trackingId,
'customer' => [
'externalId' => $user['id'],
'email' => $user['email'],
],
]),
]);
$response = curl_exec($ch);
return json_decode($response, true);
}
require 'net/http'
require 'json'
def track_lead(tracking_id, user)
uri = URI('https://track.taap.it/api/events/lead')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = "Bearer #{TAAPIT_API_KEY}"
request['Content-Type'] = 'application/json'
request.body = {
trackingId: tracking_id,
customer: {
externalId: user[:id],
email: user[:email]
}
}.to_json
response = http.request(request)
JSON.parse(response.body)
end
func trackLead(trackingID string, user User) error {
payload := map[string]interface{}{
"trackingId": trackingID,
"customer": map[string]string{
"externalId": user.ID,
"email": user.Email,
},
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
"https://track.taap.it/api/events/lead",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
return nil
}
Suivre une Vente
trackingId pour les ventes : Si le customer a déjà été tracké via un
événement lead, le trackingId est optionnel pour les événements de
vente. Vous n’avez besoin que du customerExternalId pour lier la vente au
customer existant. Si c’est un nouveau customer (pas de lead préalable),
trackingId est requis.
export async function POST(request: Request) {
const body = await request.json();
const cookieStore = cookies();
const trackingId = cookieStore.get('ta_tid')?.value || body.trackingId;
// Vérifier le paiement
const order = await verifyPayment(body);
// Suivre la vente
// trackingId est optionnel si le customer a déjà été tracké via un événement lead
await taapit.track.sale({
trackingId, // Optionnel si le customer existe déjà
customer: {
externalId: order.userId, // Requis - lie au customer existant ou en crée un nouveau
email: order.customerEmail,
},
amount: order.total, // ex: 149.99 (PAS en centimes)
currency: order.currency, // ex: 'eur'
metadata: {
orderId: order.id,
productIds: order.items.map(i => i.productId),
},
});
return Response.json({ success: true });
}
# Avec trackingId (nouveau customer ou premier tracking)
curl -X POST https://track.taap.it/api/events/sale \
-H "Authorization: Bearer taapit_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"trackingId": "rLnWe1uz9t282v7g",
"customer": {
"externalId": "user_123",
"email": "[email protected]"
},
"amount": 99.99,
"currency": "eur",
"metadata": {
"orderId": "order_456"
}
}'
# Sans trackingId (customer déjà tracké via un événement lead)
curl -X POST https://track.taap.it/api/events/sale \
-H "Authorization: Bearer taapit_sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"externalId": "user_123"
},
"amount": 99.99,
"currency": "eur"
}'
Le amount doit être en unités de devise, pas en centimes.
- ✅
amount: 29.99 pour 29,99€
- ❌
amount: 2999 (cela serait interprété comme 2999€)
Référence API
Endpoints
| Événement | Endpoint |
|---|
| Lead | POST https://track.taap.it/api/events/lead |
| Vente | POST https://track.taap.it/api/events/sale |
Authentification
Authorization: Bearer taapit_sk_xxx
Corps de la requête
{
"trackingId": "rLnWe1uz9t282v7g",
"customer": {
"externalId": "user_123",
"email": "[email protected]",
"firstname": "John",
"lastname": "Doe",
"phoneNumber": "+33612345678",
"avatarUrl": "https://example.com/avatar.jpg"
},
"amount": 99.99, // Vente seulement
"currency": "eur", // Vente seulement
"metadata": {}
}
| Champ | Type | Requis | Description |
|---|
trackingId | string | Voir ci-dessous | Le ta_tid du cookie/URL |
customer.externalId | string | Oui | Votre ID utilisateur interne |
customer.email | string | Non | Email de l’utilisateur |
amount | number | Vente | Montant en unités de devise |
currency | string | Vente | Code ISO 4217 (eur, usd…) |
metadata | object | Non | Données personnalisées |
Quand trackingId est-il requis ? - Événements lead : trackingId
est toujours requis - Événements vente : - Si le customerExternalId
a déjà été tracké (via un événement lead précédent), trackingId est
optionnel - Si c’est un nouveau customer (pas d’événement lead préalable),
trackingId est requis pour créer l’enregistrement client
Réponse
Bonnes pratiques
1. Récupérer l’ID de suivi de plusieurs sources
const cookieStore = cookies();
const trackingId =
cookieStore.get("ta_tid")?.value || // Cookie (préféré)
body.trackingId || // Corps de la requête
new URL(request.url).searchParams.get("ta_tid"); // Paramètre URL
2. Toujours suivre après confirmation
// ✅ Bien - Suivre après confirmation du paiement
const paymentResult = await processPayment();
if (paymentResult.success) {
await taapit.track.sale({...});
}
// ❌ Mal - Suivre avant confirmation
await taapit.track.sale({...});
const paymentResult = await processPayment(); // Pourrait échouer !
3. Stocker l’ID de suivi pour une utilisation ultérieure
// Lors de la création d'une session checkout
const session = await stripe.checkout.sessions.create({
metadata: { ta_tid: trackingId }, // Stocker pour le webhook
});
// Plus tard dans le webhook, le récupérer
const trackingId = session.metadata.ta_tid;
4. Logger les échecs de tracking
const result = await taapit.track.sale({...});
if (!result.success) {
console.error('Échec du tracking Taapit:', result.error);
// Ne pas faire échouer l'opération principale - le tracking est secondaire
}
Prochaines étapes