@pixby-analytics/analytics-sdk

Browser SDK for sending product analytics events to Pixby.

Install

Published package:

pnpm add @pixby-analytics/analytics-sdk

Local workspace package during development:

pnpm add /Users/aryankhan/Desktop/Work/pixby/sdk

Usage

import analytics from "@pixby-analytics/analytics-sdk";

analytics.init("demo_project_key", {
  apiUrl: "http://localhost:8080"
});

analytics.identify("user_1", {
  name: "Ava Patel",
  email: "[email protected]",
  orgId: "org_1",
  role: "admin",
  plan: "pro"
});

analytics.track("project_created", {
  project_id: "123"
});

Web Script

For website installs without bundling the package into app code:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@pixby-analytics/analytics-sdk/dist/web.global.js"
  data-project-key="demo_project_key"
  data-api-url="https://pixby-analytics.onrender.com"
></script>

The web bundle automatically:

• initializes the SDK from data-* attributes
• tracks the initial page_viewed
• tracks SPA route changes through pushState, replaceState, popstate, and hashchange
• tracks Core Web Vitals: LCP, INP, CLS, FCP, and TTFB
• loads project-level autocapture settings from Pixby
• tracks outbound links, file downloads, form submits, and JavaScript errors when enabled
• optionally tracks marked clicks when an element has data-pixby-capture
• exposes window.pixbyAnalytics for optional manual tracking

Web Vitals are sent as web_vital_measured events with metric, value, rating, unit, path, url, and title properties. The dashboard aggregates these into p75 field metrics for each web analytics project.

Autocapture events are intentionally privacy-limited. form_submitted records form metadata only, not field values. Marked click capture is opt-in and sends element_clicked only for elements explicitly tagged with data-pixby-capture.

<button data-pixby-capture="pricing_cta">Start trial</button>

You can disable specific autocapture types from the Pixby setup screen without changing the script URL. Script attributes can also override settings in emergencies:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@pixby-analytics/analytics-sdk/dist/web.global.js"
  data-project-key="demo_project_key"
  data-api-url="https://pixby-analytics.onrender.com"
  data-autocapture-errors="false"
></script>

The script URL intentionally does not pin an npm version. Customers can install it once, and future SDK releases are picked up after the package is published and the CDN cache refreshes. If a customer needs strict stability, they can pin a specific version manually.

Web user profiles

Pixby creates visitor profiles from the stable anonymous id automatically. If your site has a logged-in user, call identify() after login or account hydration:

<script>
  window.pixbyAnalytics?.identify("user_123", {
    name: "Ava Patel",
    email: "[email protected]",
    orgId: "org_1",
    plan: "pro"
  });
</script>

If name and email are missing, the dashboard assigns a deterministic Faker-generated pseudonym to the actor. The same project and actor id will always resolve to the same generated name.

API

init(projectKey, options?)

Initializes the client and starts the background flush loop.

Options:

• apiUrl
• flushIntervalMs
• flushAt
• storageKey
• headers

identify(userId, traits?)

Associates future events with a known user and event-time traits.

Traits with name, email, and orgId are used by user profiles. Anonymous visitors still get profiles from anonymousId, with a labelled generated pseudonym when no real name is provided.

track(event, properties?, context?)

Queues an event for delivery.

flush()

Immediately attempts to send queued events.

Build

pnpm --filter @pixby-analytics/analytics-sdk build

The package outputs:

• dist/index.js for ESM consumers
• dist/index.cjs for CommonJS consumers
• dist/index.d.ts for TypeScript

Versioning and publish flow

Create a changeset:

pnpm changeset

Review version updates:

pnpm version:sdk

Publish:

pnpm release:sdk

Dry-run the package before publishing:

pnpm --filter @pixby-analytics/analytics-sdk pack:check
pnpm --filter @pixby-analytics/analytics-sdk publish:dry-run

The dry-run script uses a temporary npm cache under /tmp so it can succeed even if your local ~/.npm cache has permission issues.

Real npm publish checklist

1. Log into npm:

npm login

2. Confirm the package name you want is available:

npm view @pixby-analytics/analytics-sdk

3. Build and inspect the tarball:

pnpm --filter @pixby-analytics/analytics-sdk pack:check

4. Run a publish dry run:

pnpm --filter @pixby-analytics/analytics-sdk publish:dry-run

5. Publish for real:

cd sdk
npm publish --access public

Notes before public publish

• The SDK is licensed under MIT.
• If you want richer npm metadata later, add repository, homepage, and bugs fields once the public repo URL is final.

Next.js example

App Router client bootstrap:

"use client";

import { useEffect } from "react";
import analytics from "@pixby-analytics/analytics-sdk";

export function PixbyProvider() {
  useEffect(() => {
    analytics.init(process.env.NEXT_PUBLIC_PIXBY_PROJECT_KEY!, {
      apiUrl: process.env.NEXT_PUBLIC_PIXBY_API_URL
    });
  }, []);

  return null;
}

Mount the provider near the root layout and call identify() and track() from client components after user or feature actions are known.