> ## 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.

# Migrate to 2.0

> Upgrade an existing @bilyai/js integration to the stable 2.0 contract.

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.1`.

```bash theme={null}
npm view @bilyai/js version
```

Install the current compatible 2.x release.

```bash theme={null}
npm install @bilyai/js@^2.0.1
```

## Preserve the exact tracking URL

Earlier integrations often passed only a tracking origin:

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

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

```typescript theme={null}
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.

In SDK-based applications, remove separate script tags, manual injection helpers, and framework script components.

## 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](/api-reference/events) for every normalized alias.

## Verify the upgrade

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

<Card title="Verification checklist" icon="circle-check" href="/guides/verification">
  Confirm installation and event behavior before you update production.
</Card>