Intégration côté client

Suivez les leads et ventes directement depuis le navigateur. Cette méthode est simple à implémenter mais peut être bloquée par les bloqueurs de publicités.

Le suivi côté client peut être bloqué par les bloqueurs de publicités. Pour une fiabilité maximale, nous recommandons fortement l’Intégration côté serveur.

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

Ensuite, configurez votre workspace Taapit :

Accéder aux paramètres Conversion

Dans votre dashboard Taapit, allez dans Paramètres → Conversion
Dans le dropdown, sélectionnez Intégration manuelle côté client

Ajouter vos hostnames autorisés

Dans la section Allowed Hostnames, ajoutez les domaines de votre site (ex: example.com, www.example.com)
Cliquez sur Enregistrer

Le SDK ne fonctionnera que sur les domaines listés dans vos hostnames autorisés. N’oubliez pas d’ajouter les versions www et non-www si nécessaire.

Obtenir votre clé publique

Copiez votre Publishable Key (commence par taapit_pk_)
Vous utiliserez cette clé dans les étapes suivantes

Si vous n’avez pas encore de clé publique, cliquez sur Generate Key pour en créer une.

Installation

Choisissez votre méthode préférée :

Package NPM (React/Next.js)
Balise Script (Sans Build)

Installer le SDK

npm install taapit-sdk

Ajouter le composant Analytics

Ajoutez le composant Analytics à votre layout racine pour capturer automatiquement le ta_tid :

app/layout.tsx

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

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

Obtenez votre clé publique depuis le Dashboard Taapit.

Ajoutez ce script dans votre <head> HTML ou avant </body> :

<script 
  src="https://taap.it/api/sdk" 
  data-publishable-key="taapit_pk_xxx"
></script>

Le script automatiquement :

Capture le ta_tid depuis l’URL quand les utilisateurs arrivent
Le stocke dans un cookie pendant 365 jours
Expose l’objet global taapit

Méthodes alternatives :

<!-- Via paramètre URL -->
<script src="https://taap.it/api/sdk?key=taapit_pk_xxx"></script>

<!-- Ou configurer programmatiquement -->
<script src="https://taap.it/api/sdk"></script>
<script>
  taapit.configure({ publishableKey: 'taapit_pk_xxx' });
</script>

Suivre un Lead

Un lead est un client potentiel qui montre de l’intérêt (inscription, soumission de formulaire, démarrage d’essai).

trackingId pour les leads : Le trackingId est toujours requis pour les événements lead. Il est automatiquement détecté depuis le cookie ta_tid défini quand l’utilisateur a cliqué sur un lien Taapit.

Package NPM
Balise Script

components/signup-form.tsx

'use client';

import { useTaapitAnalytics } from 'taapit-sdk/react';

export function SignUpForm() {
  const { trackLead, isReady, trackingId } = useTaapitAnalytics();

  const handleSubmit = async (formData: FormData) => {
    const email = formData.get('email') as string;
    const name = formData.get('name') as string;
    
    // Créer l'utilisateur dans votre système
    const user = await createUser({ email, name });
    
    // Suivre le lead avec Taapit
    trackLead({
      customer: {
        externalId: user.id,      // Requis: votre ID utilisateur
        email: user.email,
        firstname: user.firstName,
        lastname: user.lastName,
      },
      metadata: {
        source: 'signup-form',
        plan: 'free-trial',
      },
    });
  };

  return (
    <form action={handleSubmit}>
      <input name="name" placeholder="Nom" required />
      <input name="email" type="email" placeholder="Email" required />
      <button type="submit">Démarrer l'essai gratuit</button>
    </form>
  );
}

Import direct (alternative)

import { taapit } from 'taapit-sdk/react';

export function SignUpButton() {
  const handleClick = async () => {
    const user = await signUp();
    taapit.trackLead({
      customer: { externalId: user.id, email: user.email },
    });
  };

  return <button onClick={handleClick}>S'inscrire</button>;
}

<script>
  document.getElementById('signup-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    
    const formData = new FormData(e.target);
    
    // Créer l'utilisateur via votre API
    const response = await fetch('/api/signup', {
      method: 'POST',
      body: formData,
    });
    const user = await response.json();
    
    // Suivre le lead
    taapit.trackLead({
      customer: {
        externalId: user.id,
        email: formData.get('email'),
        firstname: formData.get('name').split(' ')[0],
        lastname: formData.get('name').split(' ').slice(1).join(' '),
      },
    });
    
    window.location.href = '/dashboard';
  });
</script>

Suivre une Vente

Une vente est une transaction complétée (achat, abonnement, paiement).

trackingId pour les ventes : Si le customer a déjà été tracké via un événement lead, le trackingId est optionnel. 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), l’utilisateur doit avoir un cookie ta_tid valide (défini en cliquant sur un lien Taapit).

Package NPM
Balise Script

components/checkout.tsx

'use client';

import { useTaapitAnalytics } from 'taapit-sdk/react';

export function CheckoutButton({ cart, user }) {
  const { trackSale } = useTaapitAnalytics();

  const handlePurchase = async () => {
    // Traiter le paiement
    const order = await processPayment(cart);
    
    // Suivre la vente avec Taapit
    trackSale({
      customer: {
        externalId: user.id,
        email: user.email,
      },
      amount: cart.total,  // ex: 49.99 (PAS en centimes)
      currency: 'eur',     // Code ISO 4217
      metadata: {
        orderId: order.id,
        items: cart.items.length,
      },
    });
    
    router.push(`/order/${order.id}`);
  };

  return (
    <button onClick={handlePurchase}>
      Finaliser l'achat - {cart.total}€
    </button>
  );
}

<script>
  document.getElementById('checkout-btn').addEventListener('click', async () => {
    // Traiter le paiement via votre API
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ cartId: 'cart_123' }),
    });
    const order = await response.json();
    
    // Suivre la vente
    taapit.trackSale({
      customer: {
        externalId: order.userId,
        email: order.customerEmail,
      },
      amount: order.total,
      currency: order.currency,
      metadata: { orderId: order.id },
    });
    
    window.location.href = `/order/${order.id}`;
  });
</script>

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€)

Méthodes disponibles

// Obtenir l'ID de suivi actuel
const trackingId = taapit.getTrackingId();

// Suivre un lead (trackingId est TOUJOURS requis - auto-détecté depuis le cookie)
taapit.trackLead({
  customer: {
    externalId: 'user_123',    // Requis
    email: '[email protected]',
    firstname: 'John',
    lastname: 'Doe',
    phoneNumber: '+33612345678',
    avatarUrl: 'https://example.com/avatar.jpg',
  },
  metadata: { ... },  // Données personnalisées optionnelles
});

// Suivre une vente
// trackingId est optionnel si le customer a déjà été tracké via un événement lead
taapit.trackSale({
  customer: { externalId: 'user_123' },  // Requis - lie au customer existant
  amount: 99.99,      // Requis
  currency: 'eur',    // Requis (ISO 4217)
  metadata: { ... },
});

Bonnes pratiques

1. Toujours suivre après confirmation

// ✅ Bien - Suivre après que l'action est confirmée
const user = await createUser(data);
taapit.trackLead({ customer: { externalId: user.id } });

// ❌ Mal - Suivre avant confirmation
taapit.trackLead({ customer: { externalId: 'pending' } });
const user = await createUser(data); // Pourrait échouer !

2. Gérer l’absence d’ID de suivi

const trackingId = taapit.getTrackingId();

if (trackingId) {
  taapit.trackLead({...});
}
// Continuez votre flux même sans tracking

3. Utiliser des external IDs stables

// ✅ Bien - Utiliser votre ID de base de données
customer: { externalId: user.id }

// ❌ Mal - N'utilisez pas de valeurs transitoires
customer: { externalId: session.id }

Limitations

Les bloqueurs de publicités peuvent bloquer les requêtes de tracking
Les restrictions du navigateur peuvent empêcher la définition des cookies
La fermeture de page avant la fin du tracking perd l’événement

Pour les conversions critiques comme les ventes, considérez l’Intégration côté serveur.

Commencer

Conversions

Référence API

Intégration côté client

Prérequis

Installation

Suivre un Lead

Import direct (alternative)

Suivre une Vente

Méthodes disponibles

Bonnes pratiques

1. Toujours suivre après confirmation

2. Gérer l’absence d’ID de suivi

3. Utiliser des external IDs stables

Limitations

Prochaines étapes

Intégration côté serveur

Référence API

Commencer

Conversions

Référence API

​Prérequis

​Installation

​Suivre un Lead

​Import direct (alternative)

​Suivre une Vente

​Méthodes disponibles

​Bonnes pratiques

​1. Toujours suivre après confirmation

​2. Gérer l’absence d’ID de suivi

​3. Utiliser des external IDs stables

​Limitations

​Prochaines étapes

Intégration côté serveur

Référence API

Prérequis

Installation

Suivre un Lead

Import direct (alternative)

Suivre une Vente

Méthodes disponibles

Bonnes pratiques

1. Toujours suivre après confirmation

2. Gérer l’absence d’ID de suivi

3. Utiliser des external IDs stables

Limitations

Prochaines étapes