Intégration du SDK

Le SDK navigateur RefCampaign reste passif tant que votre plateforme de gestion du consentement (CMP) ne transmet pas le choix du visiteur pour l'attribution. Le simple chargement du script ne crée aucune session d'attribution et ne capture aucune visite.

Démarrage rapide

1. 1

   Charger le SDK passif

   <script src="https://sdk.refcampaign.com/v4.js?s=rcst_JETON_PUBLIC_DU_SITE" async></script>

2. 2

   Transmettre la décision de la CMP

   Appelez le SDK une première fois après résolution du choix mémorisé par la CMP, puis après chaque acceptation ou retrait :

   async function appliquerConsentementAttribution(accepte) {
     return window.RefCampaignBrowser.setConsent({ attribution: accepte })
   }

   Une acceptation envoie un signal d'installation depuis l'origine configurée du marchand. La capacité d'attribution est confirmée séparément depuis la checklist authentifiée du marchand dans RefCampaign. Sur une URL telle que https://marchand.example/?ref=fabrice, l'acceptation crée aussi une session propriétaire _rc_sid pendant 90 jours. Un refus n'envoie aucune requête navigateur. Un retrait ultérieur supprime la session.

3. 3

   Transmettre la session consentie au checkout

   const sessionId = window.RefCampaignBrowser.getSessionId()
   
   await fetch('/api/checkout', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ priceId, sessionId }),
   })

   Côté serveur, ajoutez la metadata refcampaign_session uniquement si sessionId existe. Le checkout doit continuer normalement sans session.

Installation npm

pnpm add @refcampaign/sdk

import { RefCampaignBrowser } from '@refcampaign/sdk'

RefCampaignBrowser.configure({
  siteToken: 'rcst_JETON_PUBLIC_DU_SITE',
  debug: true,
})

await RefCampaignBrowser.setConsent({ attribution: choixCmp === 'accepted' })

Choisissez un seul chemin navigateur : CDN ou npm. Le jeton public du site peut être utilisé dans le navigateur ; n'y exposez jamais une clé secrète RefCampaign.

Cycle de vie du consentement

Votre CMP reste la source de vérité. RefCampaign ne conserve pas le choix de consentement.

• Acceptation initiale ou mémorisée : appelez setConsent({ attribution: true }).
• Refus initial : appelez setConsent({ attribution: false }).
• Rechargement : rejouez la décision mémorisée par la CMP.
• Retrait : appelez immédiatement la branche false.

Le Marchand est responsable du recueil du consentement et de la conservation des preuves exigées par la loi applicable. En cas de refus, la visite navigateur n'est pas attribuée automatiquement. Une conversion peut encore être attribuée grâce à une information connue indépendamment par le serveur, comme un coupon, un code de parrainage explicite ou un code affilié déjà rattaché à la commande.

Attribution Stripe

Pour un abonnement Checkout, conservez la metadata sur la Checkout Session et la Subscription :

const metadata = sessionId ? { refcampaign_session: sessionId } : {}

const checkout = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: priceId, quantity: 1 }],
  metadata,
  subscription_data: { metadata },
  success_url: 'https://marchand.example/success',
  cancel_url: 'https://marchand.example/pricing',
})

Pour un paiement unique, ajoutez la même metadata au Payment Intent.

Identifier un clic consenti

Après connexion ou inscription, vous pouvez rattacher un hash SHA-256 calculé côté client au clic consenti courant :

await RefCampaignBrowser.identify(currentUser.email)

L'email en clair ne quitte jamais le navigateur. Sans session consentie, cet appel ne fait rien.

Conversions manuelles

Utilisez le client serveur pour les paiements hors Stripe ou une attribution connue indépendamment :

import { RefCampaignServer } from '@refcampaign/sdk'

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

await rc.trackConversion({
  orderId: 'ord_42',
  sessionId,
  // Ou affiliateCode si votre serveur connaît déjà le partenaire.
  amount: 4900,
  currency: 'EUR',
  metadata: { payment_method: 'paypal' },
})

Les montants sont exprimés en centimes entiers. orderId sert de clé d'idempotence.

Déclarez un remboursement total ou partiel avec le même identifiant de commande :

await rc.refundConversion({ orderId: 'ord_42' })

await rc.refundConversion({
  orderId: 'ord_42',
  amount: 1000,
  reason: 'retour partiel',
})

Checklist de vérification

1. Refusez sur ?ref=fabrice : aucune requête de capture et aucune session d'attribution.
2. Acceptez : une requête de capture et _rc_sid disponible pour le checkout consenti.
3. Rechargez : le choix CMP rejoué expose la session existante.
4. Retirez le consentement : la session est supprimée.
5. Finalisez un checkout sans session : l'achat doit quand même réussir.