# SDK reference

| SDK | How to get it | Status |
|---|---|---|
| Browser script | `<script src="https://analyticsapi.specvista.com/api/v1/sdk.js">` | Live |
| Node.js and NestJS | `npm install specvista-analytics-node` | Prepared, not yet on npm. Check with `npm view specvista-analytics-node version` |
| React Native and Expo | `npm install specvista-analytics-rn` | Prepared, not yet on npm. Check with `npm view specvista-analytics-rn version` |
| Anything else | The HTTP API | Live. See [API reference](https://analytics.specvista.com/docs/api.md) |

Until a package is on npm, use the plain HTTP helpers in [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md) and [Add tracking to a React Native app](https://analytics.specvista.com/docs/track-react-native.md).

## Browser script

Script attributes: `data-api-key`, `data-domain`, `data-api-url`, `data-privacy-url` and `data-consent-mode`. Details and the consent rules are in [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md).

| Global | Does |
|---|---|
| `saTrack(event, properties?)` | Sends a custom event once the visitor has accepted analytics |
| `saIdentify(userId, traits?)` | Attaches an identity and uses `userId` on later events, once accepted |
| `saConsent.open()` | Reopens the consent banner |
| `saConsent.choice()` | `"full"`, `"essential"` or `null` |

The script sends a `pageview` on load and on every `pushState`, `replaceState` and `popstate` that changes the path.

## specvista-analytics-node

Node.js 18 or later.

| Export | Does |
|---|---|
| `initAnalytics({ apiKey, apiUrl?, source?, timeoutMs? })` | Configures the SDK. `apiUrl` defaults to `https://analyticsapi.specvista.com/api/v1`, `source` to `backend`, `timeoutMs` to 5000 |
| `track(event, properties?)` | Sends an event. `properties.userId` and `properties.sessionId` become top-level fields. Drops names that do not match `^[a-z][a-z0-9._:-]{1,79}$` (case-insensitive) |
| `identify(userId, { email?, name?, ...traits })` | Attaches an identity |
| `new AnalyticsService(apiKey, apiUrl?, timeoutMs?)` | A class wrapper with `track` and `identify`, for dependency injection |

Calls return straight away, do nothing before `initAnalytics`, and swallow network errors and timeouts.

## specvista-analytics-rn

Peer dependencies: `react-native` and `@react-native-async-storage/async-storage`. Optional: `expo-application` and `expo-device`.

| Export | Does |
|---|---|
| `initAnalytics({ apiKey, apiUrl?, userId?, appVersion?, appBuild?, audience?, environment? })` | Configures the SDK and sends `app_open`. `audience` is `general` or `child`. `environment` defaults to `development` in `__DEV__` builds and `production` otherwise |
| `track(event, properties?)` | Sends an event with session, platform, app and locale context |
| `trackScreen(name, properties?)` | Sends `screen_view` with `screen` set to the name |
| `identify(userId, { email?, name?, ...traits })` | Sets the user for later events and attaches an identity. Does nothing for `audience: "child"` |
| `setUserId(userId)` | Sets the user for later events without an identify call |
| `reset()` | Clears the user and starts a new session, for sign-out |
| `stopAnalytics()` | Stops sending and clears the stored session and install ids |