> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK

> Track website activity, users, and attribution with @datalyr/web.

The Web SDK tracks website activity, user identity, sessions, and attribution.

## Install

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @datalyr/web
    ```

    ```ts theme={null}
    import datalyr from '@datalyr/web'

    datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' })
    await datalyr.ready()
    ```
  </Tab>

  <Tab title="Script tag">
    ```html theme={null}
    <script
      defer
      src="https://track.datalyr.com/dl.js"
      data-workspace-id="YOUR_WORKSPACE_ID"
    ></script>
    ```
  </Tab>
</Tabs>

Choose one installation method. Do not install the package and script tag on the same page.

## Track an event

```ts theme={null}
datalyr.track('signup_clicked', {
  location: 'pricing_page'
})
```

## Identify a user

```ts theme={null}
datalyr.identify('user_123', {
  email: 'person@example.com',
  plan: 'pro'
})
```

Call `identify` after the user signs in or when you otherwise know their stable ID.

## Track a page

```ts theme={null}
datalyr.page({
  title: 'Pricing',
  variant: 'A'
})
```

The SDK tracks the first page view and SPA navigation by default. Use `page` when you need to record one manually.

## Core methods

| Method                       | Use it to                                       |
| ---------------------------- | ----------------------------------------------- |
| `init(config)`               | Initialize the SDK with a workspace ID.         |
| `ready()`                    | Wait for asynchronous initialization to finish. |
| `track(name, properties?)`   | Track an event.                                 |
| `identify(userId, traits?)`  | Attach a stable ID and traits to the visitor.   |
| `page(properties?)`          | Track a page view manually.                     |
| `alias(userId, previousId?)` | Link two IDs that belong to the same person.    |
| `reset()`                    | Clear identity when a user signs out.           |
| `flush()`                    | Send queued events immediately.                 |
| `optOut()` / `optIn()`       | Change tracking preference.                     |
| `setConsent(consent)`        | Apply analytics and marketing consent.          |

## Privacy

```ts theme={null}
datalyr.setConsent({
  analytics: true,
  marketing: false
})
```

Use `reset()` on logout so the next user does not inherit the previous user’s identity.

## Configuration

Only `workspaceId` is required. These are the options most implementations need.

| Option                        | Type                                        | Default      | What it controls                                         |
| ----------------------------- | ------------------------------------------- | ------------ | -------------------------------------------------------- |
| `workspaceId`                 | `string`                                    | Required     | The workspace that receives events.                      |
| `debug`                       | `boolean`                                   | `false`      | Console logging during development.                      |
| `trackPageViews`              | `boolean`                                   | `true`       | Tracks the first page view.                              |
| `trackSPA`                    | `boolean`                                   | `true`       | Tracks client-side navigation.                           |
| `trackSessions`               | `boolean`                                   | `true`       | Adds session data to events.                             |
| `sessionTimeout`              | `number`                                    | `60`         | Session timeout in minutes.                              |
| `attributionWindow`           | `number`                                    | `90`         | Attribution window in days.                              |
| `trackedParams`               | `string[]`                                  | `[]`         | Additional URL parameters to capture.                    |
| `privacyMode`                 | `'standard' \| 'strict'`                    | `'standard'` | Limits collection in strict mode.                        |
| `respectGlobalPrivacyControl` | `boolean`                                   | `true`       | Respects the browser GPC signal.                         |
| `respectDoNotTrack`           | `boolean`                                   | `false`      | Respects the browser DNT signal when enabled.            |
| `cookieDomain`                | `string \| 'auto'`                          | `'auto'`     | Cookie domain used for identity.                         |
| `cookieExpires`               | `number`                                    | `365`        | Cookie lifetime in days.                                 |
| `autoIdentify`                | `boolean`                                   | `false`      | Enables automatic email identification.                  |
| `enableContainer`             | `boolean`                                   | `true`       | Loads configured container scripts.                      |
| `platform`                    | `'shopify' \| 'checkoutchamp' \| 'generic'` | —            | Enables platform-specific behavior.                      |
| `stripePaymentLinks`          | `boolean`                                   | `true`       | Adds Datalyr identity to supported Stripe payment links. |

<Note>
  Start with the defaults. Change batching, retry, cookie, or attribution options only when your implementation requires it.
</Note>

## Identity

Use a stable ID from your own system:

```ts theme={null}
datalyr.identify(currentUser.id, {
  email: currentUser.email,
  plan: currentUser.plan
})
```

Useful identity methods:

| Method             | Returns                                              |
| ------------------ | ---------------------------------------------------- |
| `getAnonymousId()` | Persistent anonymous browser ID.                     |
| `getVisitorId()`   | Current visitor ID.                                  |
| `getUserId()`      | Identified user ID, or `null`.                       |
| `getDistinctId()`  | User ID when identified; otherwise the anonymous ID. |
| `getSessionId()`   | Current session ID.                                  |

Use `alias(newId, previousId)` only when both IDs belong to the same person. Use `reset()` for logout or account switching.

## Attribution

```ts theme={null}
const attribution = datalyr.getAttribution()
const journey = datalyr.getJourney()
```

The SDK captures supported click IDs, UTM parameters, and referrer data. URL values are redacted before collection when they contain known sensitive parameters.

You can also set known attribution manually:

```ts theme={null}
datalyr.setAttribution({
  utm_source: 'partner',
  utm_campaign: 'spring_launch'
})
```

## Checkout metadata

Use the SDK helpers when creating a checkout on your server:

```ts theme={null}
const stripe = datalyr.getStripeMetadata()
const whop = datalyr.getWhopCheckoutMetadata()
```

These helpers return the current visitor identity in the shape expected by the supported checkout flow.

## Super properties

Super properties are added to every later event:

```ts theme={null}
datalyr.setSuperProperties({ app_version: '2.4.0' })
datalyr.unsetSuperProperty('app_version')
```

## Lifecycle

```ts theme={null}
await datalyr.flush()
datalyr.destroy()
```

`flush()` sends queued events. `destroy()` removes listeners and stops the SDK; only use it when the integration is being torn down permanently.