Passer au contenu principal
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

Taapit Visual manual integration

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 :
  1. Créez un deeplink Taapit pointant vers votre site ou landing page
  2. Activez le suivi des conversions sur votre lien :
    • Allez dans les paramètres de votre lien dans le dashboard Taapit
    • Activez Suivi des conversions
  3. 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

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 });
}

Suivre un Lead

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 });
}

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 });
}
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énementEndpoint
LeadPOST https://track.taap.it/api/events/lead
VentePOST 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": {}
}
ChampTypeRequisDescription
trackingIdstringVoir ci-dessousLe ta_tid du cookie/URL
customer.externalIdstringOuiVotre ID utilisateur interne
customer.emailstringNonEmail de l’utilisateur
amountnumberVenteMontant en unités de devise
currencystringVenteCode ISO 4217 (eur, usd…)
metadataobjectNonDonné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