init()

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

function init(options: BilyInitOptions): void;

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

Start with the exact URL

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.

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

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

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:

init("https://tracking.example.com", { verbose: false });

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

Reference

Methods

Types

Choose a signature

Start with the exact URL

Control loading

Configure every option

Keep the URL valid

Call it again safely

Stay safe during server rendering

Keep an older integration working

ready()

Migrate to 2.0

​Choose a signature

​Start with the exact URL

​Control loading

​Configure every option

​Keep the URL valid

​Call it again safely

​Stay safe during server rendering

​Keep an older integration working

ready()

Migrate to 2.0

Choose a signature

Start with the exact URL

Control loading

Configure every option

Keep the URL valid

Call it again safely

Stay safe during server rendering

Keep an older integration working