# Convalytics

Bijection component for server-side analytics tracking with Convalytics

- Package: @bijectionhq/convalytics
- Category: Integrations
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/convalytics/tree/7ac95d6ab3baf4454fe065345fd2e0fc958abc4d
- Upstream: https://github.com/Dan-Cleary/convalytics-convex-component/tree/46c2effc03914718546861ef909916a17fa712a4
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/convalytics

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/convalytics.git
cd convalytics
git checkout 7ac95d6ab3baf4454fe065345fd2e0fc958abc4d
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes convalytics-dev; check the Bijection adaptation separately.

Convalytics provides server-side analytics for Convex applications, allowing you to track product events reliably from mutations and actions. Unlike client-side tracking, server-side events bypass ad blockers and aren't lost on page unloads. It includes web analytics capabilities and provides a unified dashboard for both server events and browser page views.

### Use cases

- Track user lifecycle events like signups, upgrades, and feature adoption from your Convex mutations
- Monitor payment and subscription events from webhook handlers in Convex actions
- Analyze user behavior patterns without worrying about ad blockers or dropped events
- Get reliable analytics data for business metrics and product decisions
- Combine server-side product events with traditional web analytics in one dashboard

### How it works

The component integrates as a Convex component that you register in `convex.config.ts` and configure with a write key from the Convalytics dashboard. You create an analytics singleton that wraps the component with your credentials.

To track events, call `analytics.track()` from your mutations or actions, passing the Convex context and event data including name, userId, and optional properties. Events are delivered asynchronously and failures are logged without affecting your application flow.

For web analytics, you add a script tag to your HTML that points to your Convex deployment URL. The CLI tool `npx convalytics init` can automate the entire setup process, creating projects, installing dependencies, and configuring your environment variables.

### Upstream README

# convalytics-dev

Server-side analytics for Convex apps. Track events reliably from mutations and actions — server-side events aren't affected by ad blockers and are never dropped on page unload.

Pairs with the Convalytics browser script for full-stack analytics: web traffic + server-side product events in one dashboard.

## Install

```bash
npm install convalytics-dev
```

## Setup

### 1. Register the component

Add to `convex/convex.config.ts` (create it if it doesn't exist):

```typescript
import { defineApp } from "convex/server";
import analytics from "convalytics-dev/convex.config";

const app = defineApp();
app.use(analytics);

export default app;
```

### 2. Create an analytics singleton

Create `convex/analytics.ts`:

```typescript
import { components } from "./_generated/api";
import { Convalytics } from "convalytics-dev";

export const analytics = new Convalytics(components.convalytics, {
  writeKey: process.env.CONVALYTICS_WRITE_KEY!,
});
```

### 3. Set your write key

Add to your Convex environment variables (via the Convex dashboard or CLI):

```bash
npx convex env set CONVALYTICS_WRITE_KEY your_write_key_here
```

Get your write key from the [Convalytics dashboard](https://convalytics.dev).

## Usage

### Track events from mutations

```typescript
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { analytics } from "./analytics";

export const createUser = mutation({
  args: { name: v.string(), email: v.string(), plan: v.string() },
  handler: async (ctx, args) => {
    const userId = await ctx.db.insert("users", args);

    await analytics.track(ctx, {
      name: "user_signed_up",
      userId: String(userId),
      props: { plan: args.plan },
    });

    return userId;
  },
});
```

### Track events from actions

```typescript
import { httpAction } from "./_generated/server";
import { analytics } from "./analytics";

export const stripeWebhook = httpAction(async (ctx, req) => {
  const event = await req.json();

  if (event.type === "invoice.payment_succeeded") {
    await analytics.track(ctx, {
      name: "subscription_renewed",
      userId: event.data.object.customer,
      props: { amount: event.data.object.amount_paid },
    });
  }

  return new Response(null, { status: 200 });
});
```

## API

### `new Convalytics(component, options)`

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `writeKey` | `string` | Yes | Your Convalytics project write key |
| `ingestUrl` | `string` | No | Override ingest endpoint (for local dev) |

### `analytics.track(ctx, event)`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Event name (e.g. `"user_signed_up"`) |
| `userId` | `string` | Yes | Stable user identifier |
| `userEmail` | `string` | No | User email — shown in dashboard instead of raw ID |
| `userName` | `string` | No | User display name — shown in dashboard |
| `sessionId` | `string` | No | Session ID (auto-generated if omitted) |
| `timestamp` | `number` | No | Unix ms timestamp (defaults to `Date.now()`) |
| `props` | `Record<string, string \| number \| boolean>` | No | Additional properties |

Events are delivered asynchronously and never throw — analytics failures are logged but never propagate to the caller.

## Web analytics

For browser page view tracking, add to your `<head>`:

```html
<script defer src="https://YOUR_CONVEX_SITE_URL/script.js?key=YOUR_WRITE_KEY"></script>
```

Your Convex site URL is shown in the [Convalytics dashboard](https://convalytics.dev) after claiming your project, or use the CLI (below) to insert it automatically.

## Quick setup via CLI

```bash
npx convalytics init
```

Auto-provisions a project, installs the package, patches `convex.config.ts`, creates `convex/analytics.ts`, sets env vars, and inserts the script tag. No write key required — one is created for you. Pass an existing key to reuse a project:

```bash
npx convalytics init YOUR_WRITE_KEY
```

Verify the pipeline:
```bash
npx convalytics verify YOUR_WRITE_KEY
```