Intégration SDK

Le paquet @refcampaign/sdk enveloppe l'API REST publique dans un client JavaScript typé. Il tourne côté serveur (Node, routes Next.js API, edge functions) et inclut la gestion automatique des retries.

Démarrage rapide

1. 1

   Installer

   pnpm add @refcampaign/sdk
   # ou
   npm install @refcampaign/sdk

   Le paquet expose des builds ESM et CJS et supporte Node 20+, Bun et Cloudflare Workers.

2. 2

   Initialiser

   import { RefCampaign } from '@refcampaign/sdk'
   
   const refcampaign = new RefCampaign({
     apiKey: process.env.REFCAMPAIGN_API_KEY!,
   })

3. 3

   Tracker

   Envoyez une conversion dès que le client paie :

   await refcampaign.conversions.track({
     sessionId,
     amount: 49.9,
     currency: 'EUR',
   })

Par défaut le client pointe sur https://app.refcampaign.com. Surchargez avec apiUrl pour tester contre staging :

const refcampaign = new RefCampaign({
  apiKey: process.env.REFCAMPAIGN_API_KEY!,
  apiUrl: 'https://app.test.refcampaign.com',
})

Suivre une conversion

Le cas d'usage le plus courant : un client vient de payer et vous voulez attribuer la conversion au clic qui l'a amené.

await refcampaign.conversions.track({
  sessionId: trackingSessionId,
  amount: 49.9,
  currency: 'EUR',
  metadata: { orderId: 'ord_42' },
})

Le sessionId est la valeur que le SDK navigateur ou l'URL de tracking a posée sur le cookie du visiteur. Si vous ne l'avez plus (Safari ITP, paiement cross-device, flux server-only), passez customerEmailHash à la place — le SHA-256 hex de l'email client lowercased.

import { createHash } from 'node:crypto'

const customerEmailHash = createHash('sha256')
  .update(customer.email.toLowerCase())
  .digest('hex')

await refcampaign.conversions.track({
  customerEmailHash,
  amount: 49.9,
  currency: 'EUR',
})

Identifier une session

Lie un client connu à une session de tracking en cours. Utile dans les flux à deux étages : le SDK navigateur capture un clic anonyme, le client remplit le formulaire de checkout, puis votre serveur identifie la session avant que la conversion n'arrive.

await refcampaign.tracking.identify({
  sessionId: trackingSessionId,
  customerEmailHash,
})

identify() est idempotent — appelez-le deux fois avec le même sessionId renvoie le binding existant.

Utilisation depuis un Route Handler Next.js

// app/api/checkout/complete/route.ts
import { RefCampaign } from '@refcampaign/sdk'
import { NextResponse } from 'next/server'

const refcampaign = new RefCampaign({
  apiKey: process.env.REFCAMPAIGN_API_KEY!,
})

export async function POST(req: Request) {
  const { sessionId, amount, currency, orderId } = await req.json()

  await refcampaign.conversions.track({
    sessionId,
    amount,
    currency,
    metadata: { orderId },
  })

  return NextResponse.json({ ok: true })
}

Erreurs

Le SDK lève une RefCampaignError dont le champ code correspond au code d'erreur retourné par l'API :

import { RefCampaign, RefCampaignError } from '@refcampaign/sdk'

try {
  await refcampaign.conversions.track({ /* … */ })
} catch (err) {
  if (err instanceof RefCampaignError) {
    if (err.code === 'VALIDATION_FAILED') {
      // Affichez les détails de niveau champ
      console.error(err.details)
    }
    if (err.code === 'RATE_LIMIT_EXCEEDED') {
      // Backoff et retry
    }
  }
  throw err
}

Voir la liste complète dans la gestion des erreurs.

Alternative REST pure

Si vous ne pouvez pas ajouter une dépendance (contraintes Lambda layer, stack polyglotte, conformité interne), appelez les endpoints directement. Voir postback serveur à serveur.