ours-web-sdk/README.md

Ours Web SDK for analytics and privacy

# ours-web-sdk

The [Ours Privacy](https://oursprivacy.com/) Web SDK.

This package lets you send events and user identification data to Ours Privacy from your JavaScript app, without using the browser snippet. Instead of installing a script tag, you install this NPM package.

You can reference all of the [Web SDK documentation here](https://docs.oursprivacy.com/docs/web-sdk-javascript).

## Installation

```bash
npm install ours-web-sdk
```

or

```bash
yarn add ours-web-sdk
```

## Usage

```js
import ours from 'ours-web-sdk';

// Initialize once at app startup
ours.init('YOUR_TOKEN', {
  custom_domain: 'https://metrics.example.com',
});

// Track events
ours.track('Purchase Completed', {
  price: 29.99,
  item: 'T-shirt',
});

// Identify or update user properties later
ours.identify({
  email: 'user@example.com',
});
```

## API

### `ours.init(token, options)`

Initialize the SDK. Call this once before tracking.

- `token` (string): Your Ours Privacy project token.
- `options` (object): Initialization options:
  - [See options available here](https://docs.oursprivacy.com/docs/web-sdk-javascript#initialization)

---

### `ours.track(eventName, eventProperties?, userProperties?, defaultPropertyOverrides?)`

Send an event to Ours.

- `eventName` (string): Name of the event.
- `eventProperties` (object): Event-specific properties.
- `userProperties` (object): [Visitor properties to include/update.](https://docs.oursprivacy.com/docs/visitor-properties-overview#supported-visitor-properties)
- `defaultPropertyOverrides` (object): Optional per-property overrides.

---

### `ours.identify(userProperties)`

Set or update properties for the identified user. [See supported list here](https://docs.oursprivacy.com/docs/visitor-properties-overview#supported-visitor-properties)

---

## When to use this package

Use this NPM package instead of the browser script if:

- You're building a React/Vue/Next.js/Node app and want first-party integration.
- You want TypeScript types and local control over initialization.
- You don't want to load the snippet from the Ours Privacy CDN.

If you want the drop-in `<script>` tag version instead, see:

👉 [Web Script Source Guide](https://docs.oursprivacy.com/docs/web-script-source)

---

## License

MIT