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

# Plan a Bily implementation

> Turn the outcomes you need into a focused event plan, clear ownership, and safe release gates.

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.

| Field               | Question to answer                                                   |
| ------------------- | -------------------------------------------------------------------- |
| Event name          | What stable outcome occurred?                                        |
| Trigger             | What exact successful state causes the event?                        |
| Owner               | Which team owns the event contract?                                  |
| Required properties | Which fields are necessary to interpret it?                          |
| Customer data       | Which approved identity fields, if any, are needed?                  |
| Event ID            | Can the same outcome be reported by more than one system?            |
| Verification        | How will a tester prove the event fired once with the right payload? |

For ecommerce activity, start with Bily's [recognized event names](/guides/ecommerce). For application outcomes, use stable snake\_case [custom event names](/guides/custom-events).

## Install Bily one way

| Website architecture                      | Installation path                                                  |
| ----------------------------------------- | ------------------------------------------------------------------ |
| Plain HTML or a site-managed script field | The exact raw script copied from Bily                              |
| Browser application with an npm build     | `@bilyai/js`                                                       |
| React single-page application             | One root-level React integration                                   |
| Next.js App Router, Pages Router, or both | One shared client component mounted once in each active route tree |

Choose either the raw script or the npm SDK for each website surface. Using both installs Bily twice and can duplicate the initial page view.

## 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](/guides/pageviews) 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:

| Classification | Examples                                       | Default action                           |
| -------------- | ---------------------------------------------- | ---------------------------------------- |
| Operational    | page name, product ID, plan, safe status code  | Include when needed                      |
| Customer       | user ID, email, phone, address                 | Include only with purpose and permission |
| Secret         | password, session token, API key, payment data | Never include                            |

Continue with [identity and attribution](/guides/identity-attribution) and [privacy governance](/guides/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](/guides/api-mcp-selection) 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.

<CardGroup cols={2}>
  <Card title="Model events and payloads" icon="diagram-project" href="/guides/event-data-model">
    Turn your plan into a stable event contract.
  </Card>

  <Card title="Prepare the rollout" icon="rocket" href="/guides/production-rollout">
    Release in stages with clear evidence and rollback criteria.
  </Card>
</CardGroup>