@product-intelligence-hub/sdk-web

Browser SDK for Product Intelligence Hub.

Installation

npm install @product-intelligence-hub/sdk-web
# or
yarn add @product-intelligence-hub/sdk-web
# or
pnpm add @product-intelligence-hub/sdk-web

Quick Start

import PIH from "@product-intelligence-hub/sdk-web";

// Initialize the SDK
const pih = PIH.init({
  apiKey: "your-api-key",
  projectId: "proj_xxx",
  environment: "production",
  tenantId: "tenant_xxx", // optional
  debug: false,
});

// Track an event
pih.track("button_clicked", {
  button_id: "signup",
  page: "/home",
});

// Identify a user
pih.identify("user_123", {
  email: "[email protected]",
  plan: "pro",
});

Configuration Options

PIH.init({
  // Required
  apiKey: string;           // Environment API key
  projectId: string;        // Project ID (proj_xxx)
  environment: string;      // Environment name

  // Optional
  apiUrl?: string;          // Ingest API URL (has default, override for self-hosted)
  tenantId?: string;        // Tenant ID for multi-tenant apps
  debug?: boolean;          // Enable debug logging (default: false)
  flushInterval?: number;   // Batch flush interval in ms (default: 10000)
  flushAt?: number;         // Flush when queue reaches this size (default: 20)
  maxQueueSize?: number;    // Max events to queue (default: 1000)
  sessionTimeout?: number;  // Session timeout in ms (default: 1800000)

  // Autocapture
  autocapture?: {
    pageViews?: boolean;    // Track page views (default: true)
    clicks?: boolean;       // Track clicks (default: false)
    formSubmissions?: boolean; // Track form submissions (default: false)
  };

  // Callbacks
  onError?: (error: PIHError) => void;
});

API

PIH.init(config)

Initialize the SDK. Returns the client instance.

pih.track(eventName, properties?, options?)

Track an event.

pih.track("purchase_completed", {
  product_id: "prod_123",
  amount: 99.99,
  currency: "USD",
});

// With options
pih.track("critical_event", { ... }, {
  immediate: true,  // Send immediately, bypass queue
  timestamp: new Date("2024-01-01"),  // Custom timestamp
});

pih.identify(userId, traits?)

Identify the current user.

pih.identify("user_123", {
  email: "[email protected]",
  name: "John Doe",
  plan: "enterprise",
});

pih.setTenant(tenantId)

Set the tenant ID for multi-tenant applications.

pih.setTenant("tenant_456");

pih.trackPageView()

Manually track a page view.

pih.trackPageView();

pih.flush()

Force flush the event queue.

await pih.flush();

pih.reset()

Reset identity (for logout).

await pih.reset();

Autocapture

Enable automatic event capture:

PIH.init({
  // ...
  autocapture: {
    pageViews: true,      // Track page_viewed on navigation
    clicks: true,         // Track element_clicked
    formSubmissions: true // Track form_submitted
  }
});

Enabling/Disabling at Runtime

// Enable
pih.enableAutocapture({ clicks: true });

// Disable
pih.disableAutocapture();

TypeScript Support

Full TypeScript support included. Types are exported from the package:

import type { PIHConfig, TrackEvent, TrackOptions } from "@product-intelligence-hub/sdk-web";

Build Outputs

• ESM: dist/index.js
• CommonJS: dist/index.cjs
• Browser (IIFE): dist/index.global.js
• TypeScript declarations: dist/index.d.ts

Related

• @product-intelligence-hub/sdk-core - Core SDK internals
• SDK Spec - Full SDK specification