Intégration côté serveur (Recommandé)

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

Comment ça marche

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.

Package NPM (React/Next.js)
Balise Script + API REST

Étape 1 : Frontend - Installer le SDK

npm install taapit-sdk

Ajoutez le composant Analytics pour capturer le ta_tid :

app/layout.tsx

import { Analytics } from "taapit-sdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

Étape 2 : Backend - Configurer votre clé API

.env

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

app/api/signup/route.ts

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": "john@example.com"
    }
  }'

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.

SDK Node.js
API REST

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": "john@example.com"
    },
    "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": "john@example.com",
    "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

{ "ok": true }

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

Intégration Stripe

Suivi automatique pour Stripe (encore plus simple).

API Track Lead

Documentation complète de l’API pour les leads.

API Track Sale

Documentation complète de l’API pour les ventes.

Commencer

Conversions

Référence API

Intégration côté serveur (Recommandé)

Comment ça marche

Prérequis

Installation

Étape 1 : Frontend - Installer le SDK

Étape 2 : Backend - Configurer votre clé API

Étape 3 : Backend - Suivre les conversions

Étape 1 : Frontend - Ajouter le script

Étape 2 : Frontend - Envoyer l’ID de suivi au backend

Étape 3 : Backend - Appeler l’API REST

Suivre un Lead

Suivre une Vente

Référence API

Endpoints

Authentification

Corps de la requête

Réponse

Bonnes pratiques

1. Récupérer l’ID de suivi de plusieurs sources

2. Toujours suivre après confirmation

3. Stocker l’ID de suivi pour une utilisation ultérieure

4. Logger les échecs de tracking

Prochaines étapes

Intégration Stripe

API Track Lead

API Track Sale

Commencer

Conversions

Référence API

​Comment ça marche

​Prérequis

​Installation

​Étape 1 : Frontend - Installer le SDK

​Étape 2 : Backend - Configurer votre clé API

​Étape 3 : Backend - Suivre les conversions

​Étape 1 : Frontend - Ajouter le script

​Étape 2 : Frontend - Envoyer l’ID de suivi au backend

​Étape 3 : Backend - Appeler l’API REST

​Suivre un Lead

​Suivre une Vente

​Référence API

​Endpoints

​Authentification

​Corps de la requête

​Réponse

​Bonnes pratiques

​1. Récupérer l’ID de suivi de plusieurs sources

​2. Toujours suivre après confirmation

​3. Stocker l’ID de suivi pour une utilisation ultérieure

​4. Logger les échecs de tracking

​Prochaines étapes

Intégration Stripe

API Track Lead

API Track Sale

Comment ça marche

Prérequis

Installation

Étape 1 : Frontend - Installer le SDK

Étape 2 : Backend - Configurer votre clé API

Étape 3 : Backend - Suivre les conversions

Étape 1 : Frontend - Ajouter le script

Étape 2 : Frontend - Envoyer l’ID de suivi au backend

Étape 3 : Backend - Appeler l’API REST

Suivre un Lead

Suivre une Vente

Référence API

Endpoints

Authentification

Corps de la requête

Réponse

Bonnes pratiques

1. Récupérer l’ID de suivi de plusieurs sources

2. Toujours suivre après confirmation

3. Stocker l’ID de suivi pour une utilisation ultérieure

4. Logger les échecs de tracking

Prochaines étapes