# 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](/docs/guides/frameworks) or [orwel.io/install](https://orwel.io/install).
</Tip>

## Installation

<CodeGroup>

```bash npm
npm install orwel@latest
```

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

</CodeGroup>

## Initialization

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

```typescript
import orwel from 'orwel';

orwel.init({
  apiKey: import.meta.env.VITE_ORWEL_KEY, // production API key orwel_pk_..., 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](/docs/guides/dev-mode). Reading data needs a separate [API key](/docs/authentication).
</Warning>

## What you can do

<CardGroup cols={2}>
  <Card title="Event Tracking" icon="signal-stream" href="/sdk/event-tracking">
    Automatic capture, custom events, and the semantic catalog.
  </Card>
  <Card title="Feature Tracking" icon="puzzle-piece" href="/sdk/feature-tracking">
    Map events to features and measure adoption.
  </Card>
  <Card title="Conversions" icon="bullseye" href="/sdk/conversions">
    Capture leads and goals, attributed across sessions.
  </Card>
  <Card title="Attribution" icon="crosshairs" href="/sdk/attribution">
    UTMs and ad click ids, first and last touch.
  </Card>
  <Card title="CDN & Infrastructure" icon="server" href="/sdk/infrastructure">
    How the SDK is distributed and how events reach the server.
  </Card>
  <Card title="SDK Reference" icon="book" href="/sdk/reference">
    Every method and init option.
  </Card>
</CardGroup>

## Core methods

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

```typescript
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](/docs/sdk/event-tracking)).

```typescript
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
const { success, reason } = await orwel.conversion('demo_request', { email: 'ada@acme.com' });
```

### Session
Update session properties.

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