Documentation SDK RefCampaign

Trackez les conversions d'affiliation de manière transparente avec la capture automatique d'ID de session et l'injection de métadonnées Stripe. Configurez votre système de tracking d'affiliation complet en moins de 5 minutes.

Installation

Installez le SDK RefCampaign avec votre gestionnaire de packages préféré :

npm install @refcampaign/sdk
# or
pnpm add @refcampaign/sdk
# or
yarn add @refcampaign/sdk

Configuration Navigateur (Côté Client)

Capturez automatiquement les ID de session d'affiliation depuis les cookies, paramètres d'URL ou localStorage.

1. Initialiser le SDK

Importez et initialisez RefCampaignBrowser avec votre clé publique. Cela doit être fait une fois au chargement de votre application.

app/layout.tsx

import { RefCampaignBrowser } from '@refcampaign/sdk'

// Initialize with your public key
RefCampaignBrowser.init({
  publicKey: 'pk_test_your_key_here'
})

2. Capturer l'ID de session

Appelez captureSession() au chargement de la page pour détecter et stocker automatiquement l'ID de session d'affiliation.

// Capture session ID on page load
const { sessionId, source } = RefCampaignBrowser.captureSession()

console.log(`Session captured from ${source}:`, sessionId)
// → Session captured from url: abc123
// → Session captured from cookie: xyz789

Exemple Next.js Complet

app/layout.tsx

'use client'

import { useEffect } from 'react'
import { RefCampaignBrowser } from '@refcampaign/sdk'

export default function RootLayout({ children }) {
  useEffect(() => {
    // Initialize SDK
    RefCampaignBrowser.init({
      publicKey: process.env.NEXT_PUBLIC_REFCAMPAIGN_PUBLIC_KEY
    })

    // Capture session ID
    RefCampaignBrowser.captureSession()
  }, [])

  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

Configuration Serveur (Backend)

Utilisez RefCampaignServer pour injecter les ID de session dans les métadonnées Stripe pour le tracking automatique des conversions.

1. Initialiser le SDK serveur

import { RefCampaignServer } from '@refcampaign/sdk'

const rc = new RefCampaignServer(process.env.REFCAMPAIGN_SECRET_KEY)

2. Obtenir les métadonnées Stripe

Générez les métadonnées à injecter dans vos sessions de paiement Stripe :

// Get session ID from cookie
const sessionId = req.cookies.get('_rc_sid')?.value

// Generate Stripe metadata
const metadata = rc.getStripeMetadata(sessionId)

// Returns: { refcampaign_session: 'abc123' }

Stratégie de Métadonnées Stripe

Le placement des métadonnées RefCampaign dépend du type de paiement que vous traitez.

Paiements Uniques

Placez les métadonnées sur le Payment Intent :

const paymentIntent = await stripe.paymentIntents.create({
  amount: 2400,
  currency: 'eur',
  metadata: rc.getStripeMetadata(sessionId)  // ✅ On Payment Intent
})

Why Payment Intent? Le Payment Intent représente le paiement unique. Les métadonnées sont automatiquement copiées sur le Charge résultant, permettant à RefCampaign de tracker la conversion.

Abonnements (Paiements Récurrents)

Placez les métadonnées sur la Subscription :

const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_xxx' }],
  metadata: rc.getStripeMetadata(sessionId)  // ✅ On Subscription ONLY
})

Pourquoi Subscription et pas Customer ?

•Chaque abonnement est lié à UNE campagne d'affiliation spécifique
•Si un client annule et se réabonne via un lien différent, le NOUVEL affilié reçoit le crédit
•Évite les conflits d'attribution quand un client a plusieurs abonnements
•Attribution équitable : les affiliés gagnent uniquement pour LEUR abonnement

Exemple de Cycle de Vie d'Abonnement

Mois 1 : Client s'abonne via le lien de l'Affilié A

→ Abonnement créé avec refcampaign_session = "session_affiliateA"

→ L'Affilié A gagne la commission initiale ✅

Mois 2-6 : Renouvellements automatiques mensuels

→ Stripe facture automatiquement le client

→ RefCampaign trouve "session_affiliateA" dans subscription.metadata

→ L'Affilié A gagne une commission récurrente chaque mois ✅

Mois 7 : Client annule son abonnement

→ Plus de charges ni de commissions récurrentes

6 mois plus tard : Client se réabonne via le lien de l'Affilié B

→ NOUVEL abonnement créé avec refcampaign_session = "session_affiliateB"

→ L'Affilié B gagne la commission (pas l'Affilié A) ✅

→ Les futurs renouvellements créditent l'Affilié B

Notes Importantes

•Stripe copie automatiquement checkout.session.metadata vers l'abonnement créé
•Vous n'avez pas besoin de définir manuellement les métadonnées d'abonnement avec Checkout Sessions
•Pour la création d'abonnement côté serveur, définissez explicitement les métadonnées sur l'objet subscription

Intégration Stripe

C'est là que la magie opère. En ajoutant les métadonnées RefCampaign à votre paiement Stripe, chaque paiement réussi attribue automatiquement les commissions au bon affilié.

Étape Critique

Vous DEVEZ inclure les métadonnées RefCampaign dans votre paiement Stripe pour que le tracking de conversion fonctionne. Sans elles, les affiliés ne recevront pas de crédit pour les ventes.

app/api/checkout/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { RefCampaignServer } from '@refcampaign/sdk'
import Stripe from 'stripe'

const rc = new RefCampaignServer(process.env.REFCAMPAIGN_SECRET_KEY!)
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(req: NextRequest) {
  // Get session ID from cookie
  const sessionId = req.cookies.get('_rc_sid')?.value

  // Get price from request
  const { priceId } = await req.json()

  // Create Stripe checkout
  const checkout = await stripe.checkout.sessions.create({
    line_items: [{ price: priceId, quantity: 1 }],

    // 🎯 CRITICAL: Inject RefCampaign metadata
    metadata: rc.getStripeMetadata(sessionId),

    mode: 'subscription',
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
  })

  return NextResponse.json({ url: checkout.url })
}

C'est tout !

RefCampaign tracke automatiquement les conversions via les webhooks Stripe lorsqu'il détecte les métadonnées refcampaign_session. Aucun code supplémentaire nécessaire.

Référence API

RefCampaignBrowser

init(config: RefCampaignBrowserConfig): void

Initialisez le SDK navigateur avec votre clé publique et le mode debug optionnel.

RefCampaignBrowser.init({
  publicKey: 'pk_test_...',  // Required
  debug: true                 // Optional
})

captureSession(): SessionCaptureResult

Capturez et stockez l'ID de session d'affiliation depuis les paramètres d'URL, cookies ou localStorage. Retourne l'ID de session et sa source.

const { sessionId, source } = RefCampaignBrowser.captureSession()
// source: 'url' | 'cookie' | 'localStorage' | 'none'

getSessionId(): string | null

Récupérez l'ID de session actuel depuis localStorage.

const sessionId = RefCampaignBrowser.getSessionId()

RefCampaignServer

getStripeMetadata(sessionId?: string): StripeMetadata

Générez l'objet de métadonnées Stripe avec l'ID de session RefCampaign. Passez ceci aux sessions de paiement Stripe pour le tracking automatique des conversions.

const metadata = rc.getStripeMetadata('abc123')
// Returns: { refcampaign_session: 'abc123' }

Variables d'Environnement

Vous avez besoin de deux clés API pour utiliser RefCampaign : une clé publique pour le code côté navigateur et une clé secrète pour le code côté serveur.

.env.local

# Public key (safe to expose in browser)
NEXT_PUBLIC_REFCAMPAIGN_PUBLIC_KEY=pk_test_...

# Secret key (server-side only, NEVER expose in browser)
REFCAMPAIGN_SECRET_KEY=sk_prod_...

Avertissement de Sécurité

Ne jamais exposer votre clé secrète dans le code du navigateur ou la committer dans le contrôle de version. Utilisez-la uniquement dans le code côté serveur.

Obtenir vos clés API

Inscrivez-vous sur RefCampaign pour obtenir vos clés publique et secrète depuis le tableau de bord.

Obtenir les Clés API

Support & Ressources

Besoin d'aide ? Nous sommes là pour vous.