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

# Fix browser tracking issues

> Restore Bily loading, preserve the exact tracking URL, and correct page-view or payload behavior.

Start with the [verification checklist](/guides/verification). If you need lifecycle details, turn on `debug: true` temporarily.

<AccordionGroup>
  <Accordion title="Restore a timed-out ready() call">
    Confirm that `init()` ran in client-mounted browser code. Compare the full `scriptUrl` with **Bily > Settings > Apps > More settings > Install tracking**.

    Check the browser **Network** panel for a blocked or failed script request. Then review your content security policy, privacy tools, browser extensions, and network restrictions.

    The default timeout is 15 seconds. You can set `loadTimeoutMs` from 1,000 to 60,000 milliseconds. A longer timeout will not fix a blocked request.
  </Accordion>

  <Accordion title="Preserve every tracking URL parameter">
    Pass the exact URL to `init({ scriptUrl })`. Do not extract its origin, append `/b.js`, decode it, or rebuild it with a URL helper.

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

    If your Bily URL contains a query string, move away from the compatibility domain form.
  </Accordion>

  <Accordion title="Remove a duplicate initial page view">
    Remove any `track("PageView")` call from the initial mount. The browser script records the first event automatically.

    Confirm that the page does not use both a raw script tag and `@bilyai/js`. The exact script should appear only once in the document.
  </Accordion>

  <Accordion title="Track missing SPA route changes">
    The automatic page view covers only the initial document. Connect `track("PageView", ...)` to the router's committed-navigation callback.

    Send the current `window.location.href` and final `document.title`. Skip the initial callback. Ignore repeated notifications for the same URL.
  </Accordion>

  <Accordion title="Choose the URL before the first init() call">
    The SDK ignores a different URL after Bily starts loading or becomes ready. Give the page one configuration owner and one exact tracking URL.

    If environments use different URLs, select the environment value before the first `init()` call. Never initialize a placeholder and replace it later.
  </Accordion>

  <Accordion title="Deliver events queued before loading">
    Make sure the application eventually calls `init()`. `track()` can queue before initialization, but delivery cannot begin until Bily loads.

    Check `maxQueueSize`. When the bounded queue is full, the SDK discards the oldest call. Avoid high-volume render or input events during startup.
  </Accordion>

  <Accordion title="Handle a null browser tracking ID">
    Expect `null` during server rendering. Call the method in browser code and handle its nullable type.

    If browser storage is blocked, the SDK can keep an in-memory identifier stable for the current page session.
  </Accordion>

  <Accordion title="Interpret ready() during server rendering">
    This behavior is expected. Public SDK calls remain safe without browser globals.

    Server resolution does not mean a browser script loaded. Initialize Bily from client-mounted code.
  </Accordion>

  <Accordion title="Correct an ecommerce total">
    Provide `order.total` when it is authoritative. Otherwise, the SDK calculates the value from each price and quantity in `order.products`.

    Put products inside `order.products` for order events. Top-level `products` do not replace products missing from `order`.
  </Accordion>

  <Accordion title="Find a missing custom event">
    Confirm that the name contains a non-whitespace character and remains consistent across calls. Verify that the successful path reached `track()`.

    Calls do not throw when browser delivery fails. Turn on `debug: true` temporarily, then use `ready()` to diagnose loading separately.
  </Accordion>
</AccordionGroup>

## Send support the right details

Collect the exact tracking URL with private credentials removed. Include the SDK version, failing event name, browser error, and steps to reproduce.

Contact [Bily support](mailto:support@bily.ai) without attaching customer payloads or secrets.

<CardGroup cols={2}>
  <Card title="Validation and debugging" icon="list-check" href="/guides/validation-debugging">
    Isolate loader, event, payload, API, and MCP boundaries.
  </Card>

  <Card title="Customer FAQ" icon="circle-question" href="/troubleshooting/faqs">
    Review direct answers to common implementation questions.
  </Card>
</CardGroup>