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

# init()

> Start Bily with an exact tracking URL and control how it loads.

Call `init()` once to load Bily in a browser document. Use the object form to preserve the exact tracking URL Bily provides.

## Choose a signature

```typescript theme={null}
function init(options: BilyInitOptions): void;

function init(
  trackingDomainOrScriptUrl: string,
  options?: BilyLegacyInitOptions,
): void;
```

## Start with the exact URL

```typescript theme={null}
import { init } from "@bilyai/js";

init({
  scriptUrl: "https://tracking.example.com/b.js?shop=store.example.com",
});
```

The SDK places `scriptUrl` on the browser script without removing or rebuilding its query string.

<Warning>
  Copy the complete URL from **Bily > Settings > Apps > More settings > Install tracking**. Keep every query parameter and encoded character.
</Warning>

## Control loading

| Option           | Type      | Default                        | Behavior                                                         |
| ---------------- | --------- | ------------------------------ | ---------------------------------------------------------------- |
| `scriptUrl`      | `string`  | Required in the preferred form | Uses the exact Bily tracking URL                                 |
| `debug`          | `boolean` | `false`                        | Logs lifecycle diagnostics, never event payloads                 |
| `maxQueueSize`   | `number`  | `100`                          | Keeps 1 to 1,000 early calls and drops the oldest when full      |
| `loadTimeoutMs`  | `number`  | `15000`                        | Waits 1,000 to 60,000 milliseconds before rejecting readiness    |
| `nonce`          | `string`  | —                              | Adds your content-security-policy nonce to the injected script   |
| `trackingDomain` | `string`  | —                              | Compatibility option that loads `/b.js` from the supplied origin |
| `verbose`        | `boolean` | `false`                        | Deprecated alias for `debug`                                     |

`scriptUrl` and `trackingDomain` are mutually exclusive in `BilyInitOptions`.

## Configure every option

```typescript theme={null}
init({
  scriptUrl: "https://tracking.example.com/b.js?shop=store.example.com",
  debug: false,
  maxQueueSize: 250,
  loadTimeoutMs: 20_000,
  nonce: document.querySelector<HTMLMetaElement>(
    'meta[name="csp-nonce"]',
  )?.content,
});
```

## Keep the URL valid

* Use HTTPS for production tracking URLs.
* Use HTTP only for local development on `localhost`, `127.0.0.1`, or `[::1]`.
* Use the object form to preserve the exact tracking URL.
* Prefer `scriptUrl` over the compatibility domain form, which builds a `/b.js` URL from the value you provide.

## Call it again safely

Calling `init()` again with the same URL does not add another script. If the page already has a script with that URL, the SDK reuses it.

After Bily starts loading or becomes ready, the SDK ignores a later call with a different URL. Keep one configuration source on each page.

After a terminal load failure, call `init()` again to retry.

## Stay safe during server rendering

During server rendering, `init()` returns without accessing browser globals. Call it from client-mounted code to start browser tracking.

## Keep an older integration working

Existing applications can keep using the string overload while you migrate:

```typescript theme={null}
init("https://tracking.example.com", { verbose: false });
```

For new integrations, use `{ scriptUrl }` to keep the exact URL intact.

<CardGroup cols={2}>
  <Card title="ready()" icon="circle-check" href="/api-reference/ready" />

  <Card title="Migrate to 2.0" icon="arrow-up" href="/migrations/2-0" />
</CardGroup>