Ce guide ajoute RefCampaign à une app Next.js avec le SDK npm. Votre CMP active ou refuse explicitement l'attribution navigateur, puis votre route checkout transmet une session RefCampaign consentie 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=rc_live_votre_secret_refcampaign
STRIPE_SECRET_KEY=sk_live_votre_secret_stripe
NEXT_PUBLIC_APP_URL=https://votreapp.com
Connecter l'attribution navigateur à votre CMP
Créez un composant client près de la racine de l'app. Transmettez-lui le choix d'attribution mémorisé et résolu par votre CMP : true, false, ou null pendant son chargement.
// app/refcampaign-client.tsx
'use client'
import { useEffect } from 'react'
import { RefCampaignBrowser } from '@refcampaign/sdk'
export function RefCampaignClient({
consentementAttribution,
}: {
consentementAttribution: boolean | null
}) {
useEffect(() => {
RefCampaignBrowser.configure({
siteToken: process.env.NEXT_PUBLIC_REFCAMPAIGN_SITE_TOKEN!,
})
}, [])
useEffect(() => {
if (consentementAttribution === null) return
void RefCampaignBrowser.setConsent({
attribution: consentementAttribution,
})
}, [consentementAttribution])
return null
}
Montez-le dans le layout racine afin que chaque landing page reçoive l'état de la CMP. Rejouez le choix mémorisé après chaque rechargement et mettez la prop à jour immédiatement après une acceptation ou un retrait.
// app/layout.tsx
import { RefCampaignClient } from './refcampaign-client'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="fr">
<body>
<RefCampaignClient consentementAttribution={cmp.consentementAttribution} />
{children}
</body>
</html>
)
}
Conserver la session sur Safari
Safari limite à 7 jours les cookies écrits en JavaScript. Pour garder _rc_sid pendant toute la fenêtre d'attribution, envoyez le sessionId capturé à un route handler et posez le même cookie depuis votre serveur. Faites-le uniquement quand setConsent retourne captured :
const result = await RefCampaignBrowser.setConsent({ attribution: true })
if (result.status === 'captured') {
await fetch('/api/refcampaign/session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ sessionId: result.sessionId }),
})
}
Le route handler n'accepte que des requêtes JSON du même site, pour qu'un autre site ne puisse pas imposer sa propre session, puis pose _rc_sid avec un Max-Age de 180 jours, Path=/, votre domaine enregistrable et sans HttpOnly, pour que le SDK puisse encore le lire et le supprimer au retrait du consentement. La référence SDK donne le handler complet.
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 https://votreapp.com/?ref=fabrice.
- Refusez l'attribution : aucune requête de capture RefCampaign et aucun cookie
_rc_sid. - Acceptez l'attribution : une requête de capture et un cookie propriétaire
_rc_sidvalable 180 jours. - Rechargez : la CMP doit rejouer l'acceptation mémorisée.
- Retirez le consentement : le cookie doit être supprimé.
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_sidest absent.
Erreurs fréquentes
N'attendez pas la page pricing pour transmettre la décision de la CMP. Les affiliés envoient souvent d'abord vers des articles, pages de comparaison ou pages docs.
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.
En cas de refus, ne recréez pas de session navigateur. Les coupons, codes de parrainage explicites et codes affiliés connus indépendamment côté serveur restent des alternatives valides lorsque la commande les contient déjà.
É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 des 8 décisions avant de lancer un programme d'affiliation SaaS couvre les règles de commission et les choix opérationnels. Pour relier chaque étape du tracking aux règles RGPD et ePrivacy, lisez l'article tracking S2S conforme RGPD.