> 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/getting-started/initialization.md).

# Initialization

## 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'
});
```

{% 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'` | `'formal'` | Tone of the snippet copy.                                                                                                                                                      |
| `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/reference/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/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.