> ## Documentation Index
> Fetch the complete documentation index at: https://www.orwel.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Orwel SDK

> Install the Orwel JavaScript SDK and start tracking behavior, features, and conversions.

The **Orwel SDK** (`orwel` on npm, current version **1.7.1**) tracks visits, sessions, events and conversions, resolves a stable visitor id, and carries first and last touch attribution. Drop it into any site or app: it captures behavior automatically and powers personalities, journeys, feature adoption and leads, all in one workspace.

> [!TIP]
>
> Looking for copy and paste steps for your stack? See [Install by framework](https://www.orwel.io/docs/guides/frameworks.md) or [orwel.io/install](https://orwel.io/install).

## Installation

```bash npm theme={null}
npm install orwel@latest
```

```html CDN theme={null}
<script src="https://cdn.jsdelivr.net/npm/orwel@1/dist/orwel.umd.js"></script>
```

## Initialization

Initialize the SDK once, at the root of your application (e.g. `App.tsx`, `main.js`), before any tracking call.

```typescript theme={null}
import orwel from 'orwel';

orwel.init({
  apiKey: import.meta.env.VITE_ORWEL_KEY, // production API key orwel_..., or orwel_dev_... while testing
  autoMonitor: true,                      // JS errors, console errors, failed requests, timings
  debug: import.meta.env.DEV,             // SDK logs in the console
});
```

> [!WARNING]
>
> The SDK key is the production API key: it can only send data, so it is safe in the browser bundle. Read it from an environment variable anyway, so production uses the production API key and development uses the [development key](https://www.orwel.io/docs/guides/dev-mode.md). Reading data needs a separate [API key](https://www.orwel.io/docs/authentication.md).

## What you can do

> [card] [Event Tracking](https://www.orwel.io/docs/sdk/event-tracking.md)
>
> Automatic capture, custom events, and the semantic catalog.

> [card] [Feature Tracking](https://www.orwel.io/docs/sdk/feature-tracking.md)
>
> Map events to features and measure adoption.

> [card] [Conversions](https://www.orwel.io/docs/sdk/conversions.md)
>
> Capture leads and goals, attributed across sessions.

> [card] [Attribution](https://www.orwel.io/docs/sdk/attribution.md)
>
> UTMs and ad click ids, first and last touch.

> [card] [CDN & Infrastructure](https://www.orwel.io/docs/sdk/infrastructure.md)
>
> How the SDK is distributed and how events reach the server.

> [card] [SDK Reference](https://www.orwel.io/docs/sdk/reference.md)
>
> Every method and init option.

## Core methods

### Identify

Associate a visitor with traits. Call when a user logs in or updates their profile.

```typescript theme={null}
orwel.identify({ email: 'user@example.com', name: 'Jane Doe', plan: 'premium' });
```

### Track

Record a named event. The code must exist in your workspace catalog (see [Event Tracking](https://www.orwel.io/docs/sdk/event-tracking.md)).

```typescript theme={null}
orwel.track('quote_created', { amount: 1200, currency: 'MXN' });
```

### Conversion

Record a high-value outcome, enriched into a lead. `conversion()` is async: it
waits for the visitor id to resolve, sends the conversion with its attribution,
and resolves with the result the server acknowledged.

```typescript theme={null}
const { success, reason } = await orwel.conversion('demo_request', { email: 'ada@acme.com' });
```

### Session

Update session properties.

```typescript theme={null}
orwel.session({ cart_value: 150.0, current_step: 'checkout' });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.