# 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`    | Use the sandbox environment for testing.                                                                                                                                       |

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

Set `sandbox: true` during development to use the sandbox environment. This lets you test your integration with simulated payments without processing real charges.

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

## 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.