Name: RefCampaign
Price: 39 EUR
Author: RefCampaign

Ce guide ajoute RefCampaign à une app Next.js avec le SDK npm. Le navigateur capture la session affiliée, votre app identifie l'utilisateur après inscription, puis votre route checkout transmet la session RefCampaign dans les metadata Stripe.

Utilisez ce chemin si votre app a déjà un frontend Next.js et une route serveur qui crée des sessions Stripe Checkout.

Prérequis

Un compte marchand RefCampaign avec une campagne active.
Une clé publique et une clé secrète RefCampaign depuis le dashboard.
Un projet Next.js App Router.
Stripe Checkout déjà installé ou prêt à l'être.

Installez le SDK :

pnpm add @refcampaign/sdk stripe

Ajoutez la clé secrète à l'environnement serveur :

REFCAMPAIGN_SECRET_KEY=sk_live_votre_secret_refcampaign
STRIPE_SECRET_KEY=sk_live_votre_secret_stripe
NEXT_PUBLIC_APP_URL=https://votreapp.com

Capturer les clics affiliés dans le navigateur

Créez un petit composant client exécuté une seule fois près de la racine de l'app.

// app/refcampaign-client.tsx
'use client'

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

export function RefCampaignClient() {
  useEffect(() => {
    RefCampaignBrowser.captureSession()
  }, [])

  return null
}

Montez-le dans le layout racine pour que chaque landing page puisse capturer les visites affiliées.

// app/layout.tsx
import { RefCampaignClient } from './refcampaign-client'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="fr">
      <body>
        <RefCampaignClient />
        {children}
      </body>
    </html>
  )
}

Identifier les utilisateurs après inscription ou connexion

Appelez identify() dès que votre app connaît l'email utilisateur. RefCampaign hash l'email dans le navigateur et l'attache au clic courant. Cela donne un fallback quand l'utilisateur convertit sur un autre appareil ou après suppression des cookies par Safari.

// app/auth/identify-refcampaign.tsx
'use client'

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

type IdentifyRefCampaignProps = {
  email: string | null
}

export function IdentifyRefCampaign({ email }: IdentifyRefCampaignProps) {
  useEffect(() => {
    if (!email) return
    void RefCampaignBrowser.identify(email)
  }, [email])

  return null
}

Rendez ce composant après login ou signup, là où votre provider de session expose l'email.

<IdentifyRefCampaign email={user.email} />

Créer Stripe Checkout avec les metadata RefCampaign

Votre route checkout doit lire le cookie de session RefCampaign et le passer à RefCampaignServer.getStripeMetadata().

// app/api/checkout/route.ts
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'
import { RefCampaignServer } from '@refcampaign/sdk'

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

export async function POST(request: NextRequest) {
  const { priceId } = await request.json()
  const sessionId = request.cookies.get('_rc_sid')?.value

  const checkout = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    subscription_data: {
      metadata: refcampaign.getStripeMetadata(sessionId),
    },
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/success`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
  })

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

Pour les paiements uniques, placez les metadata sur payment_intent_data :

const checkout = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: priceId, quantity: 1 }],
  payment_intent_data: {
    metadata: refcampaign.getStripeMetadata(sessionId),
  },
  success_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/success`,
  cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
})

Tester en local

Lancez l'app et ouvrez un lien de tracking affilié depuis le dashboard RefCampaign. Après la redirection vers votre app locale ou preview, vérifiez le stockage navigateur et la liste des cookies pour _rc_sid.

Ensuite, créez une session checkout et inspectez l'objet Stripe :

les subscriptions doivent contenir metadata.refcampaign_session ;
les paiements uniques doivent contenir la même clé sur le Payment Intent ;
aucun checkout ne doit échouer si _rc_sid est absent.

Erreurs fréquentes

N'appelez pas captureSession() uniquement sur la page pricing. Les affiliés envoient souvent vers des articles, pages de comparaison ou pages docs avant que le visiteur arrive sur le pricing.

Ne bloquez pas le checkout quand aucune session RefCampaign n'existe. Les clients directs doivent pouvoir acheter normalement.

Ne placez pas les metadata de subscription sur l'objet Stripe Customer. Un même client peut souscrire plusieurs fois via des parcours affiliés différents, donc les metadata au niveau subscription gardent l'attribution reliée au bon achat.

Étapes suivantes

Lisez le guide Stripe affiliate tracking pour les détails côté webhook, ou utilisez la référence SDK si vous avez besoin des signatures complètes. Si vous cadrez encore le programme, le guide de création d'un programme d'affiliation SaaS couvre les règles de commission et les choix opérationnels.

Suivi d'affiliation Next.js avec RefCampaign