# Obi SDK

A JavaScript SDK with dynamic content capabilities for integrating Obi into your web applications.

## Features

- Assistant interacts through voice and screen share
- DOM analysis allows the assistant to improve context
- Framework-agnostic UI components using Web Components
- Event-based API
- TypeScript support
- Session persistence across page reloads

## Configuration Options

The loader accepts the following configuration options:

| Option           | Type    | Default          | Description                                                                                                                                                                       |
| ---------------- | ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `position`       | string  | `'bottom-right'` | Position of the widget on the page. Options: `'bottom-right'`, `'bottom-left'`, `'bottom-center'`, `'top-right'`, `'top-left'`, `'top-center'`, `'middle-left'`, `'middle-right'` |
| `apiKey`         | string  | -                | Your Obi API key (required for production)                                                                                                                                        |
| `user`           | object  | -                | User information with `id` (required), `email` (optional) and `metadata` (optional)                                                                                               |
| `isActive`       | boolean | `true`           | Whether to show the widget. Set to `false` to disable the widget for specific users                                                                                               |
| `linkOnlyAccess` | boolean | `false`          | Hide the widget unless accessed via a session link. Perfect for trial periods where only customers with direct links should see the widget                                        |
| `primaryColor`   | string  | -                | Custom primary color for the widget UI (CSS color value)                                                                                                                          |

## Installation

For installation instructions, we recommend using the **obi-loader** package. This package provides a lightweight loader that will automatically fetch and initialize the full and latest SDK.

Please visit the [obi-loader npm package](https://www.npmjs.com/package/obi-loader) for installation methods and documentation.

## Widget Positioning

The widget can be positioned in one of eight positions on the page:

```js
window.obiWidgetConfig = {
  position: "bottom-right", // Options: "bottom-right", "bottom-left", "bottom-center", "top-right", "top-left", "top-center", "middle-left", "middle-right"
  apiKey: "YOUR_API_KEY",
}
```

## Trial Mode / Link-Only Access

The `linkOnlyAccess` option is perfect for trial periods where you want to control who can see and interact with the widget. When enabled, the widget remains hidden until a session is started via a direct link.

```js
window.obiWidgetConfig = {
  apiKey: "YOUR_API_KEY",
  linkOnlyAccess: true, // Widget only visible when accessed via session link
}
```

This is ideal for:

- Trial periods where only specific customers should see the widget
- Beta testing with selected users
- Controlled rollouts using session-specific links
- Demo environments where widget access is link-based

When `linkOnlyAccess` is `true`:

- Widget is invisible to regular website visitors
- Widget becomes visible only when a session is started (e.g., via URL parameters)
- Once a session ends, the widget returns to hidden state

## Session Persistence

The SDK now supports session persistence across page reloads and navigation. If a user refreshes the page or navigates to another page on your site, the session with Obi will be automatically restored when they return, providing a seamless experience.

Key features of session persistence:

- Sessions are stored locally in the browser using a namespaced localStorage implementation
- Session data is automatically cleared after a configurable expiration time (default: 5 minutes)
- When reconnecting, the previous session state is restored, including the current conversation
- Users can manually end a session at any time by using the disconnect option

No additional configuration is required to enable this feature.

## License

SEE LICENSE IN LICENSE.txt
