@sourceloop-analytics/sdk

One package for SourceLoop attribution, browser and server.

npm install @sourceloop-analytics/sdk

• Browser code: import { ... } from '@sourceloop-analytics/sdk'
• Server code: import { ... } from '@sourceloop-analytics/sdk/server'

No npm / not a coding site (WordPress, Webflow)? You don't need this package at all — paste the script snippet from your SourceLoop dashboard. The script auto-tracks pageviews, forms, and attribution with zero code. Use this SDK only in apps you build with code (React, Next.js, Node), where you want to track things like signups and checkouts precisely.

Browser (@sourceloop-analytics/sdk)

import { init, identify, track, reset, checkoutMetadata } from '@sourceloop-analytics/sdk';

init({ websiteId: 'YOUR_WEBSITE_ID' });      // once, as early as possible

identify({ email: user.email });              // on login/signup
track('signup_completed', { plan: 'pro' });   // a conversion the script can't auto-see
reset();                                       // on logout (forget the visitor)

Pageviews (including SPA route changes) are captured automatically after init().

Server (@sourceloop-analytics/sdk/server)

The reliable path for OAuth signups and payments — read the visitor's id off the request cookie in your backend and bind it.

import { Sourceloop, getAnonymousId, checkoutMetadata } from '@sourceloop-analytics/sdk/server';

// websiteId is not a secret (it's in your site snippet) — paste it directly.
const sl = new Sourceloop({ websiteId: 'YOUR_WEBSITE_ID' });

// In an OAuth callback (Google/GitHub/etc.):
const anonymousId = getAnonymousId(req);                 // reads _sl_aid cookie
await sl.identify({ anonymousId, email: user.email });   // bind identity
await sl.track({ anonymousId, email: user.email, eventName: 'signup_completed' });

// When creating a Stripe subscription server-side:
const meta = checkoutMetadata(req);                      // { sourceloop_anonymous_id }
await stripe.checkout.sessions.create({ ..., metadata: meta, subscription_data: { metadata: meta } });

See the full journey guide (cross-subdomain identity, free trial, trial→paid) below.

Which do I install where?

| Where | Install | Use | |---|---|---| | Marketing site (WordPress/Webflow) | nothing — paste the script | auto pageviews + forms | | App frontend (React/Next) | @sourceloop-analytics/sdk | pageviews, identify on login, checkoutMetadata | | App backend (Node/Next API) | @sourceloop-analytics/sdk/server | OAuth signup binding, server-side Stripe metadata, webhook conversions |

One npm install @sourceloop-analytics/sdk gives you both @sourceloop-analytics/sdk and @sourceloop-analytics/sdk/server.

Browser API

init(config), identify(traits), track(name, props?), reset(), checkoutMetadata(), getTrackingParams(), buildCrossDomainUrl(url).

Server API

new Sourceloop(config) → identify(), track(), batch(). Helpers: getAnonymousId(req), getSessionId(req), checkoutMetadata(req). req can be a Web Request/Headers, Next.js cookies()/req.cookies, a Node request, a raw Cookie header string, or a plain map.