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' }

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.