SDK

The script is the SDK's script-tag build. In an app with a bundler, use the package:

npm i @obelism/numbers-sdk

import { createNumbers } from '@obelism/numbers-sdk'

const numbers = createNumbers({
	organizationId: 'org_…',
	spaceId: 'space_…', // optional: without it, the Organization's first Space
	environment: 'production', // the default; or 'develop', 'staging'
	// endpoint: 'https://numbers.obelism.studio/api/log',
	// disableWarnings: true,
	// storage: 'session', // tab-only; or 'none': nothing stored, new id per client
})

// Page views now and on every navigation, and clicks on tagged elements.
const stop = numbers.autoTrack()
// { pageViews?, clicks?, outbound?, downloads?, forms? }

numbers.track('sign_up', 'footer_form')
numbers.formSubmit(form, 'newsletter') // or autoTrack({ forms: true })
numbers.pageView() // by hand, without autoTrack
numbers.visitor() // { id, recurring }

autoTrack({ outbound: true }) sends outbound_click for links to another site, downloads: true sends file_download for links to a file, and forms: true sends form_submit for each submitted form. Their scope is the element's data-numbers-id, or the destination, file name or form id/action; an untagged outbound link or download also carries link_domain, or file_name and file_extension, as parameters. Calling autoTrack again replaces the previous one, so the script's own page views and clicks don't double count — and it doesn't send the page view again either.

The ids are public: in a framework that only hands prefixed variables to the browser, prefix them (NEXT_PUBLIC_, VITE_, PUBLIC_). The setup page has them ready to copy as a .env.

The client is safe to create during server rendering: outside the browser every call does nothing and returns null. track returns null when it sent nothing, otherwise a promise of the response (undefined when the request failed; it never rejects).

For an event only the server knows, like a paid order, send it from the server with an API token: see events from your server.

With ImproveCopy Anchor Link

The Improve SDK (@obelism/improve-sdk 3.1 and up) sends its exposures and events through this client. A site with Improve already sends to numbers: add autoTrack() for page views and clicks, or track() for more events.

SourceCopy Anchor Link

The SDK is open source, in Obelism/sdk with the Improve and Content SDKs.