Custom events

Use custom events for meaningful product-specific outcomes outside the standard Bily catalog. track() accepts known Bily event names and your own non-empty string names.

Check the event reference first. Authentication, registration, contact, demo, trial, subscription, lead, download, and commerce outcomes already have standard names that Bily can connect consistently across destinations.

Give every outcome one stable name

Use snake_case for application events:

workspace_created
integration_connected
contacts_imported
campaign_launched
product_error_encountered

Keep IDs, timestamps, and translated labels out of event names. Put changing values in the payload.

Track the result, not the attempt

workspace.ts

import { track } from "@bilyai/js";

const workspace = await createWorkspace({ name: "North America" });

track("workspace_created", {
  workspace_id: workspace.id,
  workspace_name: workspace.name,
  plan: "growth",
});

Send a completion event only after the operation succeeds. If a failure is useful and safe to analyze, give it a separate event.

campaign.ts

import { track } from "@bilyai/js";

try {
  const campaign = await launchCampaign();
  track("campaign_launched", { campaign_id: campaign.id });
} catch (error) {
  track("product_error_encountered", {
    operation: "campaign_launch",
    error_code: getSafeErrorCode(error),
  });
  throw error;
}

Never include raw error objects. They can expose request data, stack traces, or customer content.

Correlate one logical outcome

The SDK creates event_id and ts when you omit them. Provide a stable event ID when more than one system can report the same business outcome.

track("billing_checkout_completed", {
  event_id: "checkout_session_01J2M8YQ7B",
  checkout_id: "checkout_123",
  plan: "growth",
});

Use one event_id for one logical outcome. Never reuse it for a later outcome.

Track while Bily loads

Call track() immediately after init() if needed. The SDK keeps calls while Bily loads and delivers them in order when ready.

Getting started

Plan and launch

Install Bily

Track events

Operate safely

Give every outcome one stable name

Track the result, not the attempt

Correlate one logical outcome

Track while Bily loads

track() reference

Data safety

​Give every outcome one stable name

​Track the result, not the attempt

​Correlate one logical outcome

​Track while Bily loads

track() reference

Data safety

Give every outcome one stable name

Track the result, not the attempt

Correlate one logical outcome

Track while Bily loads