SDK Reference

Methods

`init(config)`

Initialize the SDK. Call this once at app startup. Returns the API object.

import { init } from '@vibeping/sdk';
 
const vibeping = init({
  id: 'vp_abc123',       // required
  apiUrl: 'https://app.vibeping.dev', // optional
  debug: false,           // optional
});

If you call init() twice, it returns the existing instance and logs a warning in debug mode.

When using the script tag, init() is called automatically from the data-id attribute. You don't need to call it manually.

`track(name, properties?)`

Send a custom event.

// Simple event
vibeping.track('signup_clicked');
 
// With properties
vibeping.track('purchase', {
  plan: 'pro',
  price: 29,
  annual: true,
});

Parameters:

Param	Type	Description
`name`	`string`	Event name (max 100 chars)
`properties`	`Record<string, string \| number \| boolean>`	Optional key-value pairs

Script tag usage (via the global __vibeping object):

window.__vibeping.track('button_click', { color: 'blue' });

`identify(traits)`

Associate user data with the current session. Sends an identify event.

vibeping.identify({
  name: 'Jane',
  email: 'jane@example.com',
  plan: 'pro',
  signedUp: true,
});

Parameters:

Param	Type	Description
`traits`	`Record<string, string \| number \| boolean>`	User properties

Script tag usage:

window.__vibeping.identify({ name: 'Jane', plan: 'pro' });

`flush()`

Force-send all queued events immediately. The SDK batches events and sends them periodically — call flush() if you need to send them right now (e.g. before the user navigates away).

vibeping.flush();

`destroy()`

Tear down the SDK. Stops all trackers, clears timers, flushes remaining events.

vibeping.destroy();

Auto-Captured Events

These fire automatically after init(). No code needed.

`pageview`

Fires on initial page load and on SPA navigation (intercepts history.pushState and popstate). Captures:

url — current page URL
referrer — document referrer
title — page title
screenWidth / screenHeight — viewport dimensions
language — browser language

`error`

Listens to window.onerror and unhandledrejection. Captures:

message — error message
stack — stack trace
file — source file
line / column — error location
errorType — error constructor name

`vital`

Measures Core Web Vitals using the web-vitals library pattern. Captures:

name — metric name: LCP, CLS, INP, TTFB (FID may still be emitted for backward compat but is deprecated — prefer INP)
value — metric value
rating — good, needs-improvement, or poor

Event type sent to the API is vital (not web-vital).

`session`

Tracks session lifecycle:

action: 'start' — fires on init
action: 'end' — fires on page unload, includes duration in ms

Sessions are identified by a sessionId (UUID stored in sessionStorage).

Event Payload Format

All events are batched and sent as:

{
  "apiKey": "vp_abc123",
  "events": [
    {
      "type": "pageview",
      "timestamp": "2026-04-03T22:00:00.000Z",
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://myapp.com/dashboard",
      "referrer": "https://google.com",
      "title": "Dashboard",
      "screenWidth": 1920,
      "screenHeight": 1080,
      "language": "en-US"
    }
  ],
  "sdkVersion": "0.1.0",
  "sentAt": "2026-04-03T22:00:01.000Z"
}

Events are sent to POST {apiUrl}/api/v1/event. See the API Reference for details.

TypeScript Types

The SDK exports all types if you're using the npm package:

import type {
  VibePingConfig,
  VibePingAPI,
  PageviewEvent,
  VibePingErrorEvent,
  VitalEvent,
  CustomEvent,
  SessionEvent,
  TransportPayload,
} from '@vibeping/sdk';