Intégration SDK

Installez @refcampaign/sdk pour la capture navigateur, l'attribution Stripe et le suivi manuel des conversions.

Le paquet @refcampaign/sdk expose deux clients :

RefCampaignBrowser capture la session d'affiliation dans le navigateur et peut associer un hash email après inscription ou connexion.
RefCampaignServer injecte la session capturée dans les metadata Stripe ou envoie des conversions manuelles depuis votre backend.

Démarrage rapide

1
Ajouter la capture navigateur
Pour les sites no-code, sites simples ou frontends SaaS où vous ne voulez pas ajouter une dépendance au bundle, collez le script CDN dans votre <head> :
```
<script src="https://sdk.refcampaign.com/v1.js" async></script>
```
Le script capture la session depuis l'URL, le cookie ou le local storage, puis expose window.RefCampaignBrowser.
2
Installer le SDK serveur
```
pnpm add @refcampaign/sdk
# ou
npm install @refcampaign/sdk
```
Utilisez le SDK serveur partout où vous créez des paiements ou abonnements Stripe.

Ajouter les metadata Stripe

import { RefCampaignServer } from '@refcampaign/sdk'

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

const metadata = rc.getStripeMetadata(sessionId)

Passez ces metadata lors de la création de l'objet Stripe qui représente l'achat client.

Choisir un chemin d'installation

Script CDN

Utilisez ce chemin pour Webflow, Framer, WordPress, Wix, HTML statique ou tout site qui permet de coller du code personnalisé :

<script src="https://sdk.refcampaign.com/v1.js" async></script>

Cela capture les clics. L'attribution des conversions Stripe nécessite toujours le SDK serveur ci-dessous.

CDN navigateur + SDK serveur npm

C'est l'installation SaaS recommandée : gardez la capture navigateur sur le CDN et utilisez npm seulement dans votre backend.

import { RefCampaignServer } from '@refcampaign/sdk'

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

npm complet

Utilisez npm complet si vous préférez garder toute l'intégration dans le bundle de votre application :

import { RefCampaignBrowser, RefCampaignServer } from '@refcampaign/sdk'

RefCampaignBrowser.captureSession()

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

Choisissez un seul chemin navigateur : le script CDN ou RefCampaignBrowser.captureSession() depuis npm. Le SDK serveur reste nécessaire pour les metadata Stripe.

Attribution Stripe

Checkout Sessions

Pour les abonnements Stripe Checkout, ajoutez les metadata à la Checkout Session et à subscription_data afin que les factures récurrentes conservent l'attribution :

import { RefCampaignServer } from '@refcampaign/sdk'
import Stripe from 'stripe'

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

export async function POST(req: Request) {
  const { priceId, sessionId } = await req.json()
  const metadata = rc.getStripeMetadata(sessionId)

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

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

Paiements ponctuels

Pour les paiements ponctuels, placez les metadata sur le Payment Intent :

await stripe.paymentIntents.create({
  amount: 4900,
  currency: 'eur',
  metadata: rc.getStripeMetadata(sessionId),
})

Abonnements directs

Pour la création directe d'abonnements, placez les metadata sur la Subscription :

await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_xxx' }],
  metadata: rc.getStripeMetadata(sessionId),
})

Identifier les clients

Appelez identify() après connexion ou inscription pour améliorer l'attribution quand les cookies sont perdus, que Safari ITP expire le stockage, ou que le client convertit sur un autre appareil.

import { RefCampaignBrowser } from '@refcampaign/sdk'

RefCampaignBrowser.identify(currentUser.email)

Le SDK navigateur hash l'email côté client en SHA-256 avant de l'envoyer à RefCampaign.

Suivi manuel des conversions

Pour les paiements hors Stripe, envoyez la conversion depuis votre backend :

import { RefCampaignServer } from '@refcampaign/sdk'

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

const result = await rc.trackConversion({
  sessionId,
  amount: 4900,
  currency: 'EUR',
  metadata: { orderId: 'ord_42' },
})

if (!result.success) {
  console.error(result.error)
}

Les montants sont des centimes entiers. Utilisez le sessionId depuis le cookie de session du SDK navigateur, le local storage ou votre propre payload checkout.

Staging

Le SDK navigateur pointe par défaut vers https://app.refcampaign.com. Surchargez cette URL avant identify() quand vous testez contre staging :

import { RefCampaignBrowser } from '@refcampaign/sdk'

RefCampaignBrowser.configure({
  apiBase: 'https://app.test.refcampaign.com',
})

Le SDK serveur utilise apiUrl :

const rc = new RefCampaignServer(process.env.REFCAMPAIGN_SECRET_KEY!, {
  apiUrl: 'https://app.test.refcampaign.com',
})

Alternative REST pure

Si vous ne pouvez pas ajouter de dépendance, appelez directement les endpoints. Voir postback serveur à serveur.

Intégration SDK

Sur cette page