> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/sdk/web-sdk/initialization.md).

# Initialization

Initializing the **web SDK**, `@tiun/sdk`. The React Native SDK has no `init()` — it's configured through a provider instead; see [React Native SDK / Configuration](/sdk/react-native-sdk/configuration.md).

## Creating the client

Import the SDK and call `init()` once at app startup. The SDK automatically loads the tiun snippet from the backend — no script tags or extra HTML required.

```javascript
import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en', // 'en' | 'de' | 'fr'
  appearance: 'light', // 'light' | 'dark' | 'auto'
});
```

{% hint style="info" %}
**Set `language` to match your site.** Supported values are `'en'`, `'de'`, and `'fr'`. If omitted or invalid, the snippet UI falls back to `'en'`.
{% endhint %}

## Configuration options

| Option       | Type                          | Default      | Description                                                                                                                                                                    |
| ------------ | ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `snippetId`  | `string`                      | —            | **Required.** Your snippet ID from the dashboard.                                                                                                                              |
| `language`   | `'en' \| 'de' \| 'fr'`        | `'en'`       | Language for the snippet UI. The value is case-insensitive (`'En'`, `'DE'`, `' fr '` all work). Unsupported values trigger a one-time console warning and fall back to `'en'`. |
| `tone`       | `'formal' \| 'informal'`      | `'informal'` | Tone of the snippet copy.                                                                                                                                                      |
| `appearance` | `'light' \| 'dark' \| 'auto'` | `'light'`    | Color theme for the snippet UI. The value is case-insensitive. `'auto'` follows the visitor's OS setting and re-themes live when that setting changes.                         |
| `debug`      | `boolean`                     | `false`      | Enable debug logging to the console.                                                                                                                                           |
| `sandbox`    | `boolean`                     | `false`      | Target the sandbox environment (`true`) or live (`false` / omitted). Selects the API host automatically; use the snippet ID from the matching dashboard view.                  |

You can also pass event callbacks directly in the config. See [Events](/sdk/web-sdk/events.md) for the full list.

```javascript
tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
  onReady: () => console.log('ready')
});
```

## Environment setup

tiun has two **independent parallel environments** — live and sandbox — each with its own snippet ID, product IDs, and catalog. Set `sandbox: true` while developing against sandbox; omit it or set `false` for live (the default).

The SDK routes to the correct API host for you. Use the snippet ID from the environment you're targeting (sandbox vs live in the dashboard).

```javascript
tiun.init({
  snippetId: 'YOUR_SANDBOX_SNIPPET_ID',
  language: 'en',
  sandbox: true
});
```

See [Sandbox](/reference/generic/sandbox.md) for how the two environments relate and [set up your environment](/guides/getting-started/set-up-environment.md) for dashboard setup.

## Full example

```javascript
import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
  sandbox: true,
  onReady: () => {
    console.log('tiun is ready');
  },
  onError: (error) => {
    console.error('tiun error:', error.code, error.message);
  }
});
```

## Lifecycle and `destroy()`

`tiun.init()` is **idempotent**: calling it again on an initialized instance merges config rather than re-initializing. Calling `tiun.destroy()` clears listeners, runtime config, and cached user state.

The question is *can the SDK subtree remount in this host?* If it can, you want a `destroy()` on teardown so listeners and state don't accumulate. If it can't, `destroy()` is unnecessary.

| Situation                                                      | Call `destroy()`?            | Why                                                  |
| -------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------- |
| SPA root (Vue `App.vue`, single React root, Svelte/Solid root) | No                           | The root only unmounts when the document is gone     |
| React under StrictMode                                         | Yes (in `useEffect` cleanup) | StrictMode double-invokes effects in dev             |
| Component mid-tree that mounts/unmounts repeatedly             | Yes                          | Stale listeners would accumulate otherwise           |
| Micro-frontend inside a long-lived host                        | Yes                          | Host remounts the subtree without reloading the page |
| Astro island, Qwik resumability                                | Yes                          | Each island is a remount-capable subtree             |
| Server-rendered page (vanilla HTML, classic PHP)               | No                           | Page reload tears down everything                    |
| Mobile WebView swapping page URL                               | No                           | The whole document is replaced                       |
| Mobile WebView swapping DOM content without reload             | Yes                          | The same JS context survives and accumulates state   |
| Tests                                                          | Yes (per test)               | Each test wants a clean instance                     |

For framework-specific wiring, see the [SDK examples](/sdk/web-examples/vue.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tiun.io/sdk/web-sdk/initialization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.