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

# Widget Integration

> Step-by-step guide to embedding the VIZOCHOK AI shopping assistant into your storefront.

The VIZOCHOK widget is a lightweight JavaScript SDK (`@vizochok/widget`) that embeds an AI-powered shopping assistant into any web page. It uses Shadow DOM for style isolation and communicates with the VIZOCHOK backend over WebSocket for real-time streaming.

## Prerequisites

* A VIZOCHOK tenant with a **public API key** (`pk_...`)
* Your **store ID** (configured in the admin panel)

<Warning>
  Never use your secret key (`sk_...`) in frontend code. The widget requires a public key with `chat` scope only.
</Warning>

***

## Quick Start

<Steps>
  <Step title="Install the SDK">
    Install via npm or load from CDN. See [Installation](/widget/installation) for all options.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @vizochok/widget
      ```

      ```html CDN theme={null}
      <script src="https://cdn.jsdelivr.net/npm/@vizochok/widget@latest/dist/vizochok-widget.umd.js"></script>
      ```
    </CodeGroup>
  </Step>

  <Step title="Create and mount the widget">
    ```javascript theme={null}
    import { VizochokWidget } from '@vizochok/widget';

    const widget = new VizochokWidget({
      apiKey: 'pk_your_public_key',
      storeId: 'your-store-id',
      userId: 'customer-123',
      language: 'uk',
    });

    widget.mount();
    ```

    This appends the widget to `document.body`. A floating chat button appears in the bottom-right corner.
  </Step>
</Steps>

For all configuration options, see [Configuration Reference](/widget/configuration).
For theming and visual customization, see [Theming](/widget/theming).
For event callbacks and cart synchronization, see [Events & Callbacks](/widget/events).
For framework-specific examples (React, Vue, Svelte, Astro), see [Examples](/widget/examples).

***

## Inline Mode

By default, the widget renders as a floating button that opens a chat panel. You can embed it inline within a specific container instead:

```javascript theme={null}
const container = document.getElementById('chat-container');
widget.mount(container, { inline: true });
```

In inline mode:

* The widget fills 100% width and height of the container
* The floating toggle button is hidden
* The chat panel is always open
* You control visibility via the container's CSS

```html theme={null}
<div id="chat-container" style="width: 400px; height: 600px;"></div>

<script>
  const widget = new VizochokWidget({
    apiKey: 'pk_your_public_key',
    storeId: 'your-store-id',
  });
  widget.mount(document.getElementById('chat-container'), { inline: true });
</script>
```

### Switching Modes at Runtime

You can switch between inline and floating mode without losing the conversation:

```javascript theme={null}
// Switch to inline mode
widget.setMode('inline', document.getElementById('chat-panel'));

// Switch back to floating mode
widget.setMode('floating');
```

***

## Programmatic Control

The widget instance exposes methods for programmatic control:

```javascript theme={null}
widget.open();      // Open the chat panel
widget.close();     // Close the chat panel
widget.toggle();    // Toggle open/closed
widget.newChat();   // Clear history and start a new conversation
widget.unmount();   // Remove widget from DOM, preserve session in sessionStorage
widget.destroy();   // Remove widget and clear all session data
```

### Dynamic Store Switching

If the user changes their delivery address and the nearest store changes, update the widget without re-creating it:

```javascript theme={null}
// User selected a new delivery address → your backend resolved a different store
widget.setStoreId('store-kyiv-143');
```

This clears the current conversation (product availability differs between stores) and reconnects with the new store context. See [Configuration -- Store ID](/widget/configuration#store-id) for details.

***

## Shadow DOM & Style Isolation

The widget renders inside a Shadow DOM, which means:

* Your page styles do not affect the widget
* The widget styles do not leak into your page
* CSS custom properties are used for theming (set via the `theme` config)

<Info>
  Because the widget uses Shadow DOM, external CSS frameworks (Bootstrap, Tailwind) will not style the widget's internals. Use the `theme` configuration object instead.
</Info>

***

## Content Security Policy (CSP)

If your site uses a strict Content Security Policy, add these directives:

```
connect-src https://api.vizochok.com wss://api.vizochok.com;
script-src https://cdn.jsdelivr.net;
style-src 'unsafe-inline';
```

<Tip>
  The `style-src 'unsafe-inline'` is needed because the widget injects styles into its Shadow DOM. If your CSP does not allow inline styles, the widget's UI will not render correctly.
</Tip>

***

## Performance Notes

* **Bundle size**: The SDK is \~12 KB gzipped with zero external dependencies.
* **Lazy connection**: The WebSocket connection is established on `mount()`, not on instantiation.
* **Session persistence**: Conversation state is saved to `sessionStorage` so the user can refresh the page without losing context.
* **Heartbeat**: The widget maintains a heartbeat ping every 30 seconds. If no response is received within 60 seconds, the connection is automatically closed and reconnected.