Skip to main content
Bily accepts browser, customer, and acquisition context. Each value serves a different purpose. Define that purpose in your event plan.

​
Identify the browser context

getBilyTrackingId() returns the Bily identifier for the current browser context. 
import { getBilyTrackingId } from "@bilyai/js";

const trackingId = getBilyTrackingId();
The SDK keeps this value stable in browser storage when available. If storage is blocked, it can keep an in-memory value stable for the page session. During server rendering, the method returns null. The browser tracking ID:
  • is not a login identity;
  • is not a secret;
  • does not authorize a request;
  • can change when browser storage is cleared or unavailable.
Authorize protected work with your verified server session.

​
Add authenticated customer context

Attach your stable account identifier as client.userId only to events that need it. 
track("subscription_updated", {
  client: {
    userId: session.user.id,
    userGroup: session.user.plan,
  },
  subscription_id: "subscription_123",
});
The public JavaScript SDK does not expose identify(), alias(), or reset(). client.userId is approved customer context on an event—not an identity-merge command. If the same person uses more than one browser or device, use the same stable internal user ID when your consent and data policy allow it. Never use email as authorization or assume that matching contact fields merge records.

​
Handle sign-in transitions explicitly

Use this sequence:
  1. Track signed-out behavior without authenticated customer fields.
  2. After your application verifies the login, include the stable internal user ID on later events that need it.
  3. Stop attaching the previous account’s context immediately after logout.
  4. Test shared-device login and logout flows.
The browser tracking ID may stay the same through this transition. It still represents the browser context—not the authenticated account.

​
Preserve page and acquisition inputs

These fields preserve where an event occurred and where the browser came from:
FieldUse
sourceUrlCurrent page URL for an explicit event
pageTitleCurrent page title
referrerReferring URL when your policy permits it
categoryControlled event or content category
Custom propertiesApproved campaign IDs or channel labels from your application
track("PageView", {
  sourceUrl: window.location.href,
  pageTitle: document.title,
  referrer: document.referrer,
  campaign_id: "spring_launch",
});
Never place credentials, session values, or unreviewed query parameters in these fields.

​
Rely on documented attribution

Bily’s public API and MCP expose normalized analytics and customer-journey reads where available. Treat the returned fields as the reporting contract. The JavaScript SDK contract does not define:
  • an automatic first-touch or last-touch rule;
  • cross-domain browser-ID sharing;
  • anonymous-to-known identity merging;
  • exactly-once delivery from an event_id.
If a business decision needs one of these behaviors, document the requirement and verify the relevant Bily analytics output before you rely on it in production.

​
Correlate one logical outcome

The SDK generates event_id when it is missing. Provide a stable value when more than one system can observe the same logical outcome. 
track("billing_checkout_completed", {
  event_id: "checkout_session_01J2M8YQ7B",
  checkout_id: "checkout_123",
});
Use one event ID for one logical outcome. It supports correlation, but it is not an ingestion receipt.

​
Confirm the identity model

  • Browser IDs and authenticated user IDs have separate names and purposes.
  • Protected actions always use your verified session or server credential.
  • Customer fields appear only on events that require them.
  • Login, logout, shared-device, storage-cleared, and consent-denied flows are tested.
  • Attribution rules come from verified analytics output, not assumptions about the SDK.

Browser ID reference

Privacy governance