npm package: @orion-ts/browser
Description: ## Introduction
Latest version: 0.0.2-4

# OrionTracker Quickstart Guide

## Introduction

The `OrionTracker` is a front-end tracking solution designed to collect and manage user data while respecting consent preferences. This quickstart guide focuses on the three main methods: `init`, `identify`, and `track`.

## Installation

To get started with `OrionTracker`, you need to install the library from the npm registry. You can do this by running the following command in your project directory:

```bash
npm install @orion-ts/browser
```

## `init`

### Description

The `init` method initializes the tracker with the provided configuration options. It prepares all internal modules to start tracking events.

### Explanation

- **`user_distinct_id`**: Unique identifier for the user. If provided, it will be used to identify the user.
- **`identify_anonymous`**: If `true`, `$identify` event will be trigger automaticaly for anonymous user.
- **`user_metadata`**: Additional metadata about the user.
- **`auto_capture`**: If `true`, automatically captures page events.
- **`consent_mode`**: Sets consents for different tracking categories.
- **`fetch_config_endpoint`**: Optional endpoint to fetch configuration.
- **`config_expiration_delay`**: Delay before the configuration expires and needs to be refetched.
- **`session_expire_within`**: Duration after which a session expires.
- **`device_id_expire_within`**: Duration after which a device ID expires.
- **`api_host`**: Host for the tracking API.
- **`orion_api_key`**: API key for authenticating with the tracking service.

### Example

```typescript
import { OrionTracker } from "@orion-typescript/browser";

const tracker = new OrionTracker();

await tracker.init({
  user_distinct_id: "user-123",
  identify_anonymous: false,
  user_metadata: { email: "user@example.com", plan: "premium" },
  auto_capture: true,
  consent_mode: { analytics: true, marketing: false },
  fetch_config_endpoint: "https://api.example.com/config",
  config_expiration_delay: 3600, // ms
  session_expire_within: 30, // minutes
  device_id_expire_within: 365, // days
  api_host: "https://api.oriontracker.com/collect",
  orion_api_key: "your-api-key-here"
});
```

When you call `init`, the tracker configures all modules (configuration manager, consent manager, identity manager, etc.) and starts tracking `page` event if `auto_capture` is enabled.

## `identify`

### Description

The `identify` method associates a user with a specific identity. It is useful for tracking the actions of a particular user over time.

### Explanation

- **`user_distinct_id`**: Unique identifier for the user.
- **`user_metadata`**: Additional information about the user, such as email or subscription plan.

### Example

```typescript
tracker.identify({
  user_distinct_id: "user-123",
  user_metadata: { email: "user@example.com", plan: "premium" }
});
```

When you call `identify`, the tracker updates the current user's identity with the provided information. This allows you to track the actions of this specific user across different sessions.

## `track`

### Description

The `track` method tracks specific events with associated metadata. It is used to capture important actions or interactions on your site or application.

### Explanation

- **`eventName`**: Name of the event to track, e.g., "button_click".
- **`metadata`**: Additional information about the event, such as the name of the button clicked.
- **`options`**: Additional options to configure event tracking.

### Example

```typescript
tracker.track("button_click", { button_name: "Sign Up" }, { api_host: 'https://different.host.com/collect', orion_api_key: 'new_api_key' });
```

When you call `track`, the tracker captures the specified event with the provided metadata. This allows you to track specific actions and analyze user behavior.