---
name: bijection-analytics
description: "Evaluate and integrate the Analytics component with Bijection."
---

# Analytics

A Bijection analytics component for Bijection.

- Package: @bijectionhq/analytics
- Category: Integrations
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/analytics/tree/fadf5b7a09051f36e9bc4860047e6afd4db7abca
- Upstream: https://github.com/Abdssamie/convex-analytics/tree/776c531695035825263606917772501e331f8fc3
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/analytics

## Get the source

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

```sh
git clone https://github.com/bijectionhq/analytics.git
cd analytics
git checkout fadf5b7a09051f36e9bc4860047e6afd4db7abca
```

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

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @abdssamie/convex-analytics. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex Analytics. Follow the installation and configuration steps exactly.

# Convex Analytics

## Instructions

A complete first-party analytics solution for Convex applications that tracks pageviews, custom events, and user identity directly into your own database. Provides a real-time HTTP ingestion endpoint, a React dashboard component with timeseries charts, and a lightweight browser SDK with auto-batching. Events are stored and processed entirely within your Convex deployment without requiring third-party services.

### Installation

```bash
npm install @abdssamie/convex-analytics
```

Current npm version: `@abdssamie/convex-analytics@0.2.1`

## Use cases

- **Replace Google Analytics or Mixpanel** when you need complete data ownership and want analytics data in the same database as your application data
- **Track product usage metrics** like button clicks, feature adoption, and user flows with custom event properties and real-time aggregation
- **Build customer-facing analytics dashboards** using the provided React components and dashboard API for SaaS applications or client reporting
- **Monitor multi-tenant applications** by creating separate analytics sites for each tenant or environment while keeping all data in one Convex deployment
- **Comply with privacy regulations** by keeping all user analytics data on your own infrastructure without external data sharing

## How it works

The component defines its own Convex tables for sites, visitors, sessions, events, and rollups, with a two-phase ingestion architecture. Raw events flow through an HTTP endpoint that validates write keys and batches inserts, while a background worker processes pending events into aggregated visitors, sessions, and hourly/daily rollups for dashboard queries.

Setup involves installing the component with `app.use(convexAnalytics)`, registering HTTP routes with `registerRoutes()`, and provisioning a site with `provisionSite()`. The browser SDK uses `createAnalytics()` to send batched events to the HTTP ingest endpoint, or you can load it via script tag with auto-initialization.

The dashboard API exposes read functions like `getTimeseries()`, `getTopPages()`, and `getDashboardSummary()` that you wrap with your own auth logic using `exposeAnalyticsApi()`. The React dashboard component renders timeseries charts and top-dimension breakdowns by consuming these authenticated queries through standard Convex `useQuery()` hooks.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Analytics is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40abdssamie%2Fconvex-analytics)
- [GitHub repository](https://github.com/abdssamie/convex-analytics)
- [Live demo](https://convex-analytics.pages.dev)
- [Convex Components Directory](https://www.convex.dev/components/abdssamie/convex-analytics)
- [Convex documentation](https://docs.convex.dev)