Skip to main content

README

Upgather Analytics

Upgather Analytics API Documentation

The official event-tracking client library for the Upgather platform.

Welcome to the Upgather Analytics API documentation. This documentation provides detailed information about the classes, functions, and types available in @upgather/analytics. It is a thin, typed facade for sending analytics events (pageviews, interactions, registrations, and more) to the Upgather analytics endpoint, with optional event-ID validation against the Upgather EMS.

Installation​

# Using npm
npm install @upgather/analytics

# Using pnpm
pnpm add @upgather/analytics

API Reference​

For a complete list of all exported classes, functions, and types, see the API Reference.

Getting Started​

import { trackEvent, MetricType } from '@upgather/analytics';

// Set the API key once for the module-level tracking client
trackEvent.setApiKey('your-api-key');

async function recordPageview() {
  await trackEvent({
    eventId: 'aitalks26',
    organizationId: 'your-org-id',
    metricType: MetricType.pageview,
    payload: {
      url: 'https://app.upgather.com/agenda',
    },
  });
}

recordPageview();

For finer control, create a client explicitly:

import { AnalyticsClientFactory, MetricType } from '@upgather/analytics';

// Bind a default eventId so it does not need repeating on every call
const client = AnalyticsClientFactory.createClientForEvent('aitalks26');

await client.trackEvent({
  organizationId: 'your-org-id',
  metricType: MetricType.interaction,
  payload: {
    url: 'https://app.upgather.com/dashboard',
    buttonId: 'create-new',
  },
});

Key Features​

  • Complete TypeScript support with detailed type definitions
  • Module-level facade (trackEvent / trackEventLegacy) for quick setup, plus an explicit client/factory for advanced use
  • Modern and legacy endpoint formats
  • Optional API-key (x-api-key) authentication for the tracking endpoint
  • Optional event-ID validation against the Upgather EMS
  • Automatic session-ID generation (persisted in sessionStorage in the browser, in memory in Node)
  • Canonical registration payloads via the RegistrationPayload type

Metric Types​

Events are categorized by MetricType, including pageview, interaction, registration, communityEventRegistration, the assistant events (assistantOpen, assistantClose, assistantMessageSent, assistantLinkClick, assistantNewChat), login, video_view, booth_visit, and generic.

Support​

For issues and feature requests, please open an issue on the Upgather repository.

License​

This package is distributed under the MIT license.