Migrate to 2.0

Version 2.0 gives you exact-URL initialization, bounded event queuing, explicit readiness, and complete public types. Older initialization code remains compatible. The current stable release is 2.0.2.

npm view @bilyai/js version

Install the current compatible 2.x release.

npm install @bilyai/js@^2.0.2

Preserve the exact tracking URL

Earlier integrations often passed only a tracking origin:

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

In 2.0, copy the exact URL from Bily > Settings > Apps > More settings > Install tracking:

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

Keep every query parameter and encoded character. Do not reduce the URL to an origin or rebuild it in code. The string overload and trackingDomain remain available for compatibility. The deprecated verbose option remains an alias for debug.

Load Bily one way

Choose one installation path for each website surface.

Plain HTML keeps the exact raw script tag and does not install the package.
JavaScript, React, and Next.js install @bilyai/js and let init() load the script. Follow a framework guide when it reserves one script element for the SDK to reuse.

In SDK-based applications, remove unmanaged script tags, manual injection helpers, and framework script components. Keep only a framework-reserved element that the SDK explicitly reuses.

Send one page view per route

The browser script records the initial PageView automatically. Remove any manual call for that first view. For every later SPA route, send the exact event name after navigation commits:

track("PageView", {
  sourceUrl: window.location.href,
  pageTitle: document.title,
});

Add a same-URL guard so rerenders do not create duplicate page views.

Let early events queue

The SDK queues track() calls made before loading finishes. Your event code does not need to await ready(). Use ready() only for installation checks and diagnostics:

try {
  await ready();
} catch (error) {
  reportSafeLoadFailure(error);
}

Version 2.0 bounds the queue, lets you configure the load timeout, reports script load errors, and supports retry after a terminal load failure.

Confirm payload behavior

Version 2.0 now:

Supports top-level products payloads.
Defaults an omitted product quantity to 1.
Preserves product image and client userGroup fields.
Preserves zero-valued totals, taxes, discounts, and shipping fees.
Calculates an order total from product price and quantity when order.total is absent.
Adds event_id and ts when you omit them.
Accepts custom event strings while retaining known-event autocomplete.

After upgrading, run representative product, cart, checkout, and order payloads through staging.

Handle a nullable tracking ID

getBilyTrackingId() returns string | null. Update code that assumed a string:

const trackingId = getBilyTrackingId();
if (trackingId) {
  correlateBrowserSession(trackingId);
}

Expect null during server rendering.

Import types from the package root

Version 2.0 exports the complete public payload types:

import type {
  BilyAddress,
  BilyClient,
  BilyEvent,
  BilyInitOptions,
  BilyLegacyInitOptions,
  BilyOrder,
  BilyPayload,
  BilyProduct,
  KnownBilyEvent,
} from "@bilyai/js";

Do not import types from internal package files.

Adopt current event names

Compatibility aliases still work. Use current names for new code:

Replace	With
`Pageview`	`PageView`
`Add to Wishlist`	`Product Added to Wishlist`
`Category Viewed`	`ViewCategory`
`Remove from Cart`	`Product Removed From Cart`
`Search`	`Products Searched`

See the complete event name reference for every normalized alias.

Verify the upgrade

Confirm the exact tracking URL remains unchanged in the browser.
Confirm one automatic initial PageView.
Confirm one explicit event for each later SPA route.
Trigger events before loading finishes and verify their delivery order.
Test a load failure and the ready() rejection path.
Test server rendering without window or document.
Verify zero-valued order fields and optional product quantities.
Search the browser bundle for credentials and private tokens.

Verification checklist

Confirm installation and event behavior before you update production.

Getting started

Plan and launch

Install Bily

Track events

Operate safely

Preserve the exact tracking URL

Load Bily one way

Send one page view per route

Let early events queue

Confirm payload behavior

Handle a nullable tracking ID

Import types from the package root

Adopt current event names

Verify the upgrade

Verification checklist

​Preserve the exact tracking URL

​Load Bily one way

​Send one page view per route

​Let early events queue

​Confirm payload behavior

​Handle a nullable tracking ID

​Import types from the package root

​Adopt current event names

​Verify the upgrade

Verification checklist

Preserve the exact tracking URL

Load Bily one way

Send one page view per route

Let early events queue

Confirm payload behavior

Handle a nullable tracking ID

Import types from the package root

Adopt current event names

Verify the upgrade