Plan a Bily implementation

Start with a small, reviewed contract. Decide what you need to learn or operate, where each event becomes true, and who owns the result before you choose framework code.

​

Start with the decision you need to make

Write down the business decisions your implementation should support. For example:

• which product journeys lead to checkout;
• where customers leave a conversion flow;
• which campaign and store results need regular review;
• which operational actions may be performed through the API or MCP.

Map each decision to a small set of observable outcomes. Availability alone is not a reason to track every render, click, or state change.

​

Give every event an owner and proof

Use one row for each event. Review the plan with the product code. Start with Bily’s recognized event names for commerce and common application outcomes. Use a stable snake_case custom event only for a product-specific outcome that has no standard event.

​

Install Bily one way

Use one Bily loader per website surface. In most npm applications, let the SDK create it. If a framework guide reserves one script element for the SDK to reuse, keep that element and do not add another unmanaged tag.

​

Make one integration own page views

The browser script records the initial document page view. If your application changes routes without loading a new document, send one explicit PageView after each later committed route. Choose one router integration to own those later page views. It should:

1. skip the initial route callback;
2. wait for the final committed URL;
3. include the current URL and page title;
4. ignore repeated notifications for the same URL.

Read the page-view guide before you add component-level tracking.

​

Set identity and privacy boundaries

Keep these three concepts separate:

• the Bily browser tracking ID identifies a browser context;
• client.userId carries your approved authenticated account ID on an event;
• your server session authorizes protected product actions.

The browser tracking ID never authorizes a request. Include customer fields only when they have a documented purpose and the visitor’s consent allows them. Review every field: Continue with identity and attribution and privacy governance.

​

Give each developer surface one job

The browser SDK sends website events. It does not replace a server API client. Use the versioned Bily API for repeatable backend integrations and scheduled work. Use Bily MCP when a compatible AI client should discover current operations through search and run focused work through execute. The API or MCP selection guide helps you choose one surface—or combine them when the workflow needs both.

​

Prepare each environment before you build

For each environment, define:

• which Bily store and tracking URL each environment uses;
• where test events are allowed;
• who can create or revoke server credentials;
• which checks must pass before production;
• how to disable the new tracking code without changing unrelated application behavior.

Never initialize a placeholder URL and replace it later. Select the exact environment-specific tracking URL before the first init() call.

​

Know when planning is complete

Start implementation when:

• every event has an owner, trigger, required fields, and verification step;
• the team selected exactly one browser installation path;
• initial and SPA page-view ownership is explicit;
• optional customer fields have privacy approval;
• API and MCP credentials remain outside browser code;
• staging and production stores, URLs, and release gates are documented.