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

# Identity and attribution

> Keep browser identity, customer context, and attribution in their proper roles.

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.

```typescript theme={null}
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.

```typescript theme={null}
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:

| Field             | Use                                                           |
| ----------------- | ------------------------------------------------------------- |
| `sourceUrl`       | Current page URL for an explicit event                        |
| `pageTitle`       | Current page title                                            |
| `referrer`        | Referring URL when your policy permits it                     |
| `category`        | Controlled event or content category                          |
| Custom properties | Approved campaign IDs or channel labels from your application |

```typescript theme={null}
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.

```typescript theme={null}
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.

<CardGroup cols={2}>
  <Card title="Browser ID reference" icon="fingerprint" href="/api-reference/get-bily-tracking-id" />

  <Card title="Privacy governance" icon="shield-check" href="/guides/privacy-governance" />
</CardGroup>