Le paquet [`@refcampaign/sdk`](https://www.npmjs.com/package/@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
### 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 `` :
```html
```
Le script capture la session depuis l'URL, le cookie ou le local storage, puis expose `window.RefCampaignBrowser`.
### Installer le SDK serveur
```bash
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
```ts
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é :
```html
```
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.
```ts
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 :
```ts
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 :
```ts
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 :
```ts
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 :
```ts
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.
```ts
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 :
```ts
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 :
```ts
import { RefCampaignBrowser } from '@refcampaign/sdk'
RefCampaignBrowser.configure({
apiBase: 'https://app.test.refcampaign.com',
})
```
Le SDK serveur utilise `apiUrl` :
```ts
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](/fr/docs/api/integration/postback).