> ## Documentation Index
> Fetch the complete documentation index at: https://guides.klaritics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate the Klaritics Web SDK in Your Application

> Install the Klaritics Web SDK via npm or script tag, initialize with app_id and server_host, and log events, user IDs, and session properties.

The Klaritics Web SDK sends analytics events directly from the browser to your self-hosted Klaritics instance. You can install it via npm for bundler-based projects or load it from a CDN script tag for simpler setups. This guide covers installation, initialization, event logging, user and session management, and SPA behavior.

## Installation

<Tabs>
  <Tab title="npm">
    Install the package from npm:

    ```bash theme={null}
    npm install --save @deeptaai/klaritics-web-sdk
    ```

    Then import and initialize:

    ```javascript theme={null}
    import Klaritics from "@deeptaai/klaritics-web-sdk";

    Klaritics.init("YOUR_APP_ID", {
      server_host: "https://YOUR_SERVER_HOST"
    });
    ```
  </Tab>

  <Tab title="Script tag">
    Add the script tag to your HTML. The `defer` attribute ensures it loads after the page content.

    ```html theme={null}
    <script type="text/javascript" defer
      src="https://unpkg.com/@deeptaai/klaritics-web-sdk@latest">
    </script>
    ```

    Then initialize in your application code:

    ```javascript theme={null}
    Klaritics.init("YOUR_APP_ID", {
      server_host: "https://YOUR_SERVER_HOST"
    });
    ```
  </Tab>
</Tabs>

## Initialization options

You can pass additional options when calling `init`:

| Option          | Type    | Description                                       |
| --------------- | ------- | ------------------------------------------------- |
| `server_host`   | string  | Required. URL of your Klaritics instance.         |
| `honorDNT`      | boolean | Honor the browser's Do Not Track setting.         |
| `idle_time_out` | number  | Milliseconds of inactivity before a session ends. |
| `version`       | string  | Application version to attach to events.          |

## Logging events

Use `logEvent` to send standard analytics events. Use `logClientEvent` for events that are specific to your client-side logic.

<CodeGroup>
  ```javascript Standard event theme={null}
  Klaritics.logEvent("ProductClicked", {
    product_id: "sku-123",
    category: "electronics"
  });
  ```

  ```javascript Before refresh theme={null}
  // Third argument true sends the event before a page refresh
  Klaritics.logEvent("CheckoutStarted", { cart_value: 99.99 }, true);
  ```

  ```javascript Client event theme={null}
  Klaritics.logClientEvent("SoftBackPressed", { page: "settings" });
  ```
</CodeGroup>

## User and session management

```javascript theme={null}
// Identify the current user
Klaritics.setUserId("user@example.com");

// Attach user properties
Klaritics.setUserProperties({
  plan: "pro",
  signup_date: "2024-01-15"
});

// Attach session properties
Klaritics.setSessionProperties({
  campaign: "summer_sale"
});

// Retrieve the SDK-generated client ID
const clientId = Klaritics.getClientId();

// Manually control sessions
Klaritics.startNewSession();
Klaritics.endSession();
```

## Single-page applications

For SPAs, you can use your existing redirection handler to trigger events on route changes. URL-based page tracking is configured from the Klaritics dashboard and does not require additional SDK setup.