# SDK (/docs/sdk)

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

```bash
npm i @obelism/numbers-sdk
```

```ts
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](https://numbers.obelism.studio/setup) 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](/docs/api/log#from-a-storefront).

## With Improve [#with-improve]

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.

## Source [#source]

The SDK is open source, in [Obelism/sdk](https://github.com/Obelism/sdk) with the Improve and Content SDKs.