Bily JavaScript SDK

The official browser SDK for sending page views, product activity, and custom application events to Bily.

Install

npm install @bilyai/js

Initialize once

Copy the exact script URL from Bily > Settings > Apps > More settings > Install tracking. Keep every query parameter in the URL.

import { init } from "@bilyai/js";

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

The SDK safely queues calls made while the browser script loads. Repeated init() calls with the same URL do not load it twice.

Framework compatibility

The packed SDK is tested in browser ESM, React Router, Next.js App and Pages Routers, Vue 3, Nuxt 3 and 4, Svelte 5 with SvelteKit 2, Angular 20 and 21, Astro 5, Remix 2, and React Router Framework Mode 7 and 8.

The package is safe to import during server rendering. Call init() from a client-side lifecycle, then send one PageView after each client-side route change. The browser script sends the first page view, so do not send it twice.

Astro client transitions

Astro's client router replaces the document head. Declare the reserved script once with transition:persist, then initialize the SDK from that element's exact URL. The SDK reuses this one browser script; it does not add a second loader. Send later page views from astro:page-load.

---
const bilyScriptUrl = import.meta.env.PUBLIC_BILY_SCRIPT_URL;
---

<script
  id="bily-tracking-script"
  src={bilyScriptUrl}
  async
  referrerpolicy="strict-origin-when-cross-origin"
  transition:persist="bily-tracking-script"
  is:inline
></script>

<script>
  import { init } from "@bilyai/js";

  const script = document.querySelector("#bily-tracking-script");
  if (script instanceof HTMLScriptElement) init({ scriptUrl: script.src });
</script>

Change the tracking URL

Treat scriptUrl as fixed for the life of the current page. To move to a first-party tracking URL:

1. Replace the complete scriptUrl, including every query parameter.
2. Rebuild and redeploy when the value comes from a public build-time environment variable.
3. Hard reload the page, then confirm #bily-tracking-script uses the new URL.

Do not hot-switch URLs in the same document or through hot module replacement. Once this SDK instance is loading or ready, a second init() with another URL is ignored to protect the active installation and its queue. A fresh SDK instance that finds the reserved script ID attached to another URL rejects initialization instead. In either case, reload the document to change URLs. ready() never proves that a different URL replaced the active installation.

After a terminal load error, call init() explicitly to retry. Later ready() calls keep reporting that error until the retry begins.

Track an event

import { track } from "@bilyai/js";

track("Product Viewed", {
  products: [
    {
      id: "product_123",
      name: "Everyday Tee",
      price: 39,
      currency: "USD",
      quantity: 1,
    },
  ],
});

Custom application events are supported:

track("workspace_created", {
  user_id: "user_123",
  workspace_id: "workspace_456",
});

Verify loading

ready() resolves when Bily can accept queued events and rejects if the browser script fails to load.

import { ready } from "@bilyai/js";

await ready();

See the JavaScript SDK documentation for React, Next.js, event payload, and troubleshooting guides.

Contributing

Use the exact Node.js version in .nvmrc and npm version declared by packageManager. Framework smoke tests pin every direct package and resolve transitive packages from a fixed registry snapshot.