@sourcea/sdk

Sourcea browser SDK: lead attribution and conversion tracking.

It records where each visitor came from (UTM parameters, click ids such as gclid and fbclid, the GA4 client id, referrer, landing page) and sends the enquiries they make (forms, taps on your phone number) to your Sourcea workspace, with that origin attached. About 3 KB gzipped, no cookies.

Documentation: https://analytics.sourcea.io/en/docs/sdk (in French: https://analytics.sourcea.io/fr/docs/sdk)

Install

npm install @sourcea/sdk

Or with a script tag, pinned to a version:

<script src="https://cdn.jsdelivr.net/npm/@sourcea/[email protected]/dist/browser/sourcea.min.js"></script>

Usage

Create a key in the dashboard under Settings → API keys (sa_live_…). The key is public: it can only write into your workspace.

import { createSourcea } from '@sourcea/sdk';

const sourcea = createSourcea({ apiKey: 'sa_live_...' });

// On every page, after consent in the EU: where the visitor came from.
// The tab keeps one session; a page with its own utm_*/gclid starts a new one.
void sourcea.trackSession();
sourcea.trackPageView();

// No consent needed: a lead for every tap on a tel: link.
sourcea.trackPhoneClicks();

// A form.
const result = await sourcea.sendLead(
  { email: '[email protected]', message: 'Quote for a roof' },
  { kind: 'quote_request' },
);
if (!result.ok) console.warn(result.error);

Without consent to tracking, send the lead without attribution identifiers: sendLead(contact, { kind: 'contact', attribution: false }).

With the script tag, window.Sourcea is a ready-made client (Sourcea.init({ apiKey })) and window.SourceaSDK holds every other export.

API

| Export | Purpose | | --- | --- | | createSourcea(config) | Creates and initialises a SourceaClient. | | client.init(config) | { apiKey, apiUrl?, debug?, testMode? }. testMode: true stores everything the SDK sends as test data (not counted, never sent to ad platforms, notification mails marked "Test"); off by default. | | client.trackSession() | Opens the tab's session with the page's attribution, or keeps the current one. Stores an identifier. | | client.trackPageView(path?, title?) | Adds a page to the journey attached to the next lead. | | client.track(type, metadata?) | Records an event of EVENT_TYPES on the session. | | client.sendLead(contact, opts?) | Sends a lead; resolves to a SendLeadResult. | | client.trackPhoneClicks(opts?) | A lead per tap on a tel: link; returns stop(). | | captureAttribution(visitorId) | Reads the page's attribution. | | getVisitorId(), getSessionId(), setSessionId() | Storage helpers. | | readConsent(), writeConsent(), forgetTracking() | Consent helpers. | | SDK_VERSION | The SDK's version. |

Every option, default and error code is in the API reference. Changes: CHANGELOG.md.

License

MIT