SDK integration

The RefCampaign browser SDK is passive until your consent-management platform (CMP) sends the visitor's attribution choice. Loading the script alone does not create an attribution session or capture a visit.

Quickstart

1. 1

   Load the passive SDK

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

2. 2

   Forward the CMP decision

   Call the SDK once after the CMP resolves its persisted choice, then after every grant or withdrawal:

   async function applyAttributionConsent(granted) {
     return window.RefCampaignBrowser.setConsent({ attribution: granted })
   }

   A grant sends one install heartbeat from the configured merchant origin. Attribution readiness is confirmed separately from the authenticated merchant checklist in RefCampaign. On a URL such as https://merchant.example/?ref=fabrice, the grant also creates a first-party _rc_sid session for 90 days. A refusal sends no browser request. A later withdrawal deletes the session.

3. 3

   Send the consented session to checkout

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

   On the server, attach refcampaign_session metadata only when sessionId is present. Checkout must continue normally without it.

npm installation

pnpm add @refcampaign/sdk

import { RefCampaignBrowser } from '@refcampaign/sdk'

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

await RefCampaignBrowser.setConsent({ attribution: cmpChoice === 'granted' })

Choose one browser path: CDN or npm. The public site token is safe for browser use; never expose a RefCampaign secret key there.

Consent lifecycle

Your CMP remains the source of truth. RefCampaign does not store the consent choice.

• Initial grant or persisted grant: call setConsent({ attribution: true }).
• Initial refusal: call setConsent({ attribution: false }).
• Reload: replay the persisted CMP decision.
• Withdrawal: call the false branch immediately.

The merchant is responsible for obtaining consent and retaining any evidence required by applicable law. If consent is refused, the browser visit is not attributed automatically. You may still attribute a conversion using information independently known by your server, such as a coupon, an explicit referral code, or an affiliate code already attached to the order.

Stripe attribution

For a Checkout subscription, preserve the metadata on both the Checkout Session and 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://merchant.example/success',
  cancel_url: 'https://merchant.example/pricing',
})

For a one-time payment, add the same metadata to the Payment Intent.

Identify a consented click

After login or signup, you can attach a client-side SHA-256 email hash to the current consented click:

await RefCampaignBrowser.identify(currentUser.email)

The plaintext email never leaves the browser. Without a consented session, this call is a no-op.

Manual conversions

Use the server client for non-Stripe payments or independently known attribution:

import { RefCampaignServer } from '@refcampaign/sdk'

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

await rc.trackConversion({
  orderId: 'ord_42',
  sessionId,
  // Or affiliateCode when your server already knows the partner.
  amount: 4900,
  currency: 'EUR',
  metadata: { payment_method: 'paypal' },
})

Amounts are integer cents. orderId is the idempotence key.

Report a full or partial refund with the same order id:

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

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

Verification checklist

1. Refuse on ?ref=fabrice: no capture request and no attribution session.
2. Grant: one capture request and _rc_sid available to the consented checkout flow.
3. Reload: replayed CMP grant exposes the existing session.
4. Withdraw: the session is deleted.
5. Complete checkout without a session: the purchase still succeeds.