Skip to main content
Release a small, reviewed contract. Prove it with real flows. Expand only when the result matches your event plan.

​
Make the release ready

Before you begin, confirm:
  • one owner approves the event names and business meaning;
  • one browser installation path owns loading;
  • the exact production tracking URL comes from the intended Bily store;
  • page-view ownership is documented for direct loads and SPA routes;
  • customer fields have consent and privacy approval;
  • API and MCP credentials are created for the intended workload and scope;
  • every write has a verification read and rollback decision.

​
Move through four release gates

​
Gate 1: Prove the code locally

  • The project builds and type-checks.
  • Bily imports remain safe during server rendering.
  • The application sends no success event on a failed operation.
  • Event payloads contain only reviewed fields.

​
Gate 2: Prove real flows in staging

  • One Bily script loads with the exact URL.
  • One initial page view appears.
  • Later SPA routes produce one explicit page view each.
  • Representative product, checkout, order, and custom events match the event plan.
  • Login, logout, consent-denied, and storage-restricted paths behave as expected.
  • Read-only API and MCP discovery calls use the intended organization and store.

​
Gate 3: Start with limited production exposure

  • Release to the smallest practical traffic or operator group.
  • Run a short, named verification window.
  • Compare event counts to the expected product actions, not to an unrelated metric.
  • Inspect at least one real payload for every new or changed event.
  • Exercise one safe read for each new API or MCP workload.

​
Gate 4: Expand to full production

  • Expand only after the limited window passes.
  • Remove temporary SDK diagnostics.
  • Record the release time, owner, event changes, credential changes, and verification evidence.
  • Keep the rollback path available until the next stable review window.

​
Evolve events without breaking the contract

Make additive changes when possible:
  • add a new property before removing an old one;
  • keep property types stable;
  • add a new event when the business meaning changes;
  • avoid renaming events and properties in place without a migration window.
If two systems can emit the same logical outcome during a migration, give both one stable event_id and test the result. An event ID does not guarantee exactly-once ingestion.

​
Introduce API workloads one step at a time

  1. Start with GET /context and select an exact nested store URL.
  2. Verify one read-only store endpoint.
  3. Preserve x-request-id in logs.
  4. Add bounded retries only for safe reads.
  5. Before a write, read the current state and record the intended change.
  6. After a write, read the state again before reporting success.
When the first result is uncertain, do not automatically repeat a create, clone, update, toggle, delete, sync, or mutation request.

​
Keep MCP actions visible and verifiable

  1. Keep approval mode set to prompt.
  2. Use search immediately before an unfamiliar operation.
  3. Review the complete execute function, including every helper call.
  4. Begin with an identity, store, or analytics read.
  5. Introduce one approved action at a time.
  6. Verify every action with the catalog’s recommended read.
Planning metadata is advisory. One execute call can contain several helper calls, so the client review must cover the complete function.

​
Know when to roll back

Roll back or disable the new path if:
  • the script fails to become ready;
  • the initial page view duplicates;
  • a high-value event is missing or fires before success;
  • a property changes type or contains unapproved customer data;
  • an API job crosses the intended organization or store boundary;
  • an MCP action differs from the reviewed function or verification result.
If verification disagrees with the requested state, stop additional writes.

​
Confirm the result after release

In the first stable review window:
  • compare expected product outcomes with observed Bily events;
  • inspect samples across signed-out, signed-in, and consent states;
  • review API errors by status and request ID;
  • review MCP actions and their verification reads;
  • remove temporary credentials and test-only event paths;
  • update the event catalog with the final production contract.

Validation and debugging

Migration guide