Add numbers to your site
Choose the script or the SDK, allow your site's origin, and see the first visitors in the dashboard.
Script or SDK
Both send the same events, through the same endpoint, into the same reports: migrating later changes nothing in the data.
Use the script (/script.js) | Use the SDK (@obelism/numbers-sdk) |
|---|---|
| A static site, a CMS template, or anything without a build step | Anything with a bundler: Next.js, React Router, Astro, Vue, Svelte |
| The tag can load on every page, always | Analytics must wait for consent, and be stoppable when it's withdrawn |
| Its default page views and clicks are enough | You need pageViews: false and your router's own page views (shallow routes, route-level consent) |
| Nothing needs custom events from code | You send your own events, or need autoTrack's options |
The script's hard limits: it has no stop()/destroy(), so consent withdrawal takes a reload (or your consent tool's type="text/plain" machinery); its page views come from history.pushState/replaceState/popstate, so a router's shallow navigation can't be steered; its autoTrack options are reachable only by calling window.numbers.autoTrack({ … }) after it loads; and it can't be imported conditionally from a component. If any of those is yours, start with the SDK and skip step 1.
1. Add the script
Add this to every page of your site, with your Organization's id. The setup page in the dashboard shows it filled in.
<script
defer
src="https://numbers.obelism.studio/script.js"
data-organization="org_…"
data-space="space_…"
data-environment="production"
></script>It sends a page view on load and on every client-side navigation (pushState, replaceState and back/forward), with the page's path, the referrer when it is another site, and the UTM tags. It also counts clicks on tagged elements.
| Attribute | Required | What it does |
|---|---|---|
data-organization | Yes | Your Organization's id (org_…). |
data-space | No | The Space (space_…) the events belong to. Without it, the Organization's first Space. |
data-environment | No | develop, staging or production (the default). |
data-endpoint | No | Send to another URL than /api/log, such as a proxy on your own domain. |
data-debug | No | Log the development warnings (a name that isn't snake_case, an 8 KB body, a bad Organization or Space id, an unknown data-environment or data-storage). |
data-storage | No | session or none to count without a cookie (see privacy). |
The script sends to numbers' origin even when a CDN serves the file, so data-endpoint is only needed for a proxy. Without data-space it sends to the Organization's first Space; name the Space to keep one site's events together.
2. Allow your site's origin
A browser may only send events from an allowed origin. Add your site's origin on the Space's page on www.obelism.studio, under Allowed origins, for the environment it sends to. develop allows localhost on any port to start with.
Origins match exactly, or by port with :*. On Shopify Oxygen every deployment has its own preview URL, so each preview is a new origin: add the environment URL(s) you use, or turn on allow any origin for develop and staging while you test. A preview that sends to staging needs data-environment="staging" (or the SDK's environment: 'staging'), or it is judged against production's origins.
3. Check the dashboard
Open the dashboard, pick the Space and environment in the sidebar, and visit your site: the page view shows up within a minute. Events lists everything that came in, by name and scope.
Next
- Move to the SDK if a bundler, consent, or your router's navigation needs it.
- Count clicks on buttons and links.
- Send your own events, like
sign_uporpurchase. - Send events from your server, like a paid order.
- Read the reports: what each number means.