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

# Browser

> Send client-side events and page views with @glyphhq/browser.

`@glyphhq/browser` sends events from a web app. It queues messages in memory, sends them in batches, and attempts a flush when the tab is hidden or the connection returns.

## Install

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install @glyphhq/browser
  ```

  ```html Script tag theme={"dark"}
  <script src="https://cdn.jsdelivr.net/npm/@glyphhq/browser@0.1/dist/cdn.global.js"></script>
  <script>
    window.Glyph.init({ writeKey: "glyph_pk_..." });
    window.Glyph.track("user_123", "Project created");
  </script>
  ```
</CodeGroup>

The script tag build exposes `init`, `profile`, `track`, `group`, `page`, `flush`, and `reset` on `window.Glyph`. The npm package additionally exports the `GlyphBrowser` class and singleton helpers such as `getClient`.

The SDK reports its package name and version with each request. Glyph stores this as diagnostic metadata alongside the write key used for ingestion. It is not added to event properties.

<Note>
  Browser write keys are public credentials. They can ingest events but cannot read data. Use a `glyph_test_...` key during development so test events stay separate from live customer data.
</Note>

## Initialize

Create a client directly, or use `init` to share a singleton across the app:

<CodeGroup>
  ```ts Client instance theme={"dark"}
  import { GlyphBrowser } from "@glyphhq/browser";

  const glyph = new GlyphBrowser({ writeKey: "glyph_pk_..." });
  ```

  ```ts Singleton theme={"dark"}
  import { init, getClient } from "@glyphhq/browser";

  init({ writeKey: "glyph_pk_..." });

  // Anywhere else in your app:
  getClient().track("user_123", "Project created");
  ```
</CodeGroup>

Calling `init()` again disposes the previous singleton and discards its queued messages. `reset()` disposes it without creating a replacement; call it on logout.

See [Configuration & delivery](/docs/reference/configuration) for all constructor options. The browser client adds one of its own:

| Option      | Default | Description                                                                                                                    |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `autoFlush` | `true`  | Flush when the tab becomes hidden (using `keepalive` so the request outlives the page) and when the browser comes back online. |

## Identify customers with `profile`

Call `profile` when a customer signs up or logs in, or when a profile trait changes. `userId` is the stable identity key, and every profile must include `email`.

```ts theme={"dark"}
glyph.profile("user_123", {
  email: "sarah@example.com",
  name: "Sarah Chen",
  plan: "pro",
});
```

## Record actions with `track`

```ts theme={"dark"}
glyph.track("user_123", "Invoice paid", {
  amount: 4900,
  currency: "USD",
});
```

Properties are optional JSON. See [What to capture](/docs/guides/what-to-capture) for event selection and naming guidance.

## Record page views with `page`

The browser SDK exposes `page` for client-side page views:

```ts theme={"dark"}
glyph.page("user_123", "Dashboard", { path: "/dashboard" });
```

The name is optional; properties default to `{}`.

## Record account context with `group`

`group` records a group/account event on the customer's timeline. Glyph does not currently create a separate account record or provide group-level analytics.

```ts theme={"dark"}
glyph.group("user_123", "acme_inc", { plan: "enterprise" });
```

## Flushing

Messages queue locally and flush when the queue reaches `flushAt` (default 20), on the `flushIntervalMs` timer (default 5 s), or when `autoFlush` fires on tab hide or reconnect. You can also force it:

```ts theme={"dark"}
await glyph.flush(); // send everything queued now
await glyph.close(); // stop the timer, remove listeners, flush
glyph.reset();       // drop anything queued without sending (e.g. on logout)
```

The queue is not persisted to local storage. A tab close, crash, blocked request, or failed unload can lose messages. Capture payments, subscription changes, and other critical events with a server SDK.

## Known customers only

Every method takes `userId` as its first argument. Glyph does not support anonymous identities; begin tracking after signup or another point where the customer is known.