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",
});
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.
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 });
{ scriptUrl } to keep the exact URL intact.
