---
title: "Integrate Pug"
description: "Event analytics and user profiles you can wire into any app - install an SDK, POST straight to the API, or self-host the whole stack."
---

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

# Integrate Pug

Pug is open-source product analytics. Capture events, identify the people behind
them, and query the result back out - from a browser, a mobile app, your
backend, or any language that can POST JSON. Run it on Pug Cloud or
[self-host the entire stack](/self-hosting).

Custom event names work with no setup. Beyond those, Pug ships
**[127 typed events](/reference/well-known-events)** across 19 families
(commerce, auth, billing, media, support), each with a validated property
schema, so `purchase` and `signup` mean the same thing in your data as they do
in everyone else's. Capture is
[cookieless by default](/sdks/web#tracking-consent): events flow from the first
hit, and nothing is stored on the device until the reader consents.

<div class="not-content mt-6 mb-8 flex flex-col gap-3 *:w-full min-[30rem]:flex-row min-[30rem]:flex-wrap min-[30rem]:*:w-max">

[Quickstart](/get-started)

[Install with AI](/get-started/ai-setup)

[Install the Web SDK](/sdks/web)

</div>

## Initialize, then track

The whole integration, on every platform. Pick yours, then carry on in its
[SDK reference](/sdks).

### Web

```ts
import { init, track } from '@pug-sh/browser'

init('YOUR_PROJECT_ID', {
  apiKey: 'pub_YOUR_PUBLIC_KEY'
})

track('page_view')
```

Next: the [Web SDK reference](/sdks/web).

### Flutter

```dart
import 'package:pug_flutter/pug_flutter.dart';

await Pug.init(
  'YOUR_PROJECT_ID',
  const PugOptions(apiKey: 'pub_YOUR_PUBLIC_KEY'),
);

Pug.track('page_view');
```

Next: the [Flutter SDK reference](/sdks/flutter).

### Node

```ts
import { Pug } from '@pug-sh/node'

// Server-side - authenticate with your private key.
const pug = new Pug({ apiKey: process.env.PUG_PRIVATE_KEY! })

// A server has no ambient user - name the distinctId.
pug.track('user-123', 'page_view')
```

Next: the [Node SDK reference](/sdks/node).

### Ruby

```ruby
require "pug"

# Server-side - authenticate with your private key.
pug = Pug::Client.new(api_key: ENV.fetch("PUG_PRIVATE_KEY"))

# A server has no ambient user - name the distinct_id.
pug.track("user-123", "page_view")
```

Next: the [Ruby SDK reference](/sdks/ruby).

### HTTP API

```bash
# No SDK? POST events to the Connect RPC ingest endpoint.
# See /sdks/http for the full request shape.

curl -X POST https://api.pugs.dev/sdk.events.v1.EventsService/BatchCreate \
  -H "x-api-key: pub_YOUR_PUBLIC_KEY" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"eventId":"01J9...","kind":"page_view","distinctId":"anon-1","sessionId":"01J9...","occurTime":"2026-06-05T10:00:00Z"}]}'
```

Next: [integrating over HTTP](/sdks/http).

## Ways to integrate

- **Web app** - Install the Web SDK (`@pug-sh/browser`) - auto-track page views and clicks,
identify users on sign-in. [Quickstart](/get-started)
- **Mobile app** - Typed event tracking, screen and lifecycle auto-tracking, and identity for
Flutter apps. [Flutter setup](/sdks/flutter)
- **Backend or any language** - Send events and read analytics from Node with `@pug-sh/node` or Ruby with
`pug-sh` - or POST straight to the Connect RPC API from anywhere else.
[Node SDK](/sdks/node) | [Ruby SDK](/sdks/ruby)
- **Query your data** - Read insights and profiles programmatically with your private key, via the
Node or Ruby SDK or the Connect API. [API reference](/api)
- **Self-host** - Run the full stack - Postgres, ClickHouse, NATS, Dragonfly and the Go
workers - on your own infrastructure. [Self-hosting guide](/self-hosting)

## How it works

Events flow from your app through an async pipeline into analytics storage. The
same data powers Live, Insights, and Profiles.

1. **SDK** (track() & identify())
2. **API** (Connect RPC ingest)
3. **NATS** (async queue)
4. **Workers** (geo & enrichment)
5. **ClickHouse** (analytics store)
6. **Dashboard** (insights & profiles)

Ingestion is near-real-time: events appear in **Live** within seconds and in
**Insights** within the same minute. See [Core concepts](/get-started/concepts)
for the full model.

## Jump straight in

### Track

```ts
import { track } from '@pug-sh/browser'

track('button_clicked', { label: 'Sign up' })

track('purchase', {
  productId: 'sku_123',
  amount: 29.99,
  currency: 'USD'
}, { immediate: true })
```

### Identify

```ts
import { identify, reset } from '@pug-sh/browser'

// On sign-in - merges prior anonymous activity into the profile.
await identify('user-123', {
  email: 'user@example.com',
  plan: 'pro'
})

// On sign-out.
reset()
```

## Start here

- **Get started** - [Quickstart](/get-started) | [Core concepts](/get-started/concepts) |
[Install the Web SDK](/sdks/web#install) |
[Authentication](/get-started/authentication)
- **Build** - [Track events](/sdks/web#track-events) |
[Identity and sessions](/sdks/web#identify-and-sessions) |
[Consent and privacy](/sdks/web#consent-and-privacy) |
[Flutter](/sdks/flutter) | [Node](/sdks/node) | [Ruby](/sdks/ruby) |
[HTTP](/sdks/http)
- **Reference** - [API reference](/api) | [Well-known events](/reference/well-known-events) |
[Auto-properties](/reference/auto-properties) |
[Self-hosting](/self-hosting) | [GitHub](https://github.com/pug-sh)

Source: https://docs.pug.sh/index.mdx