Skip to main content

AnalyticsClient

Upgather Analytics

Upgather Analytics / AnalyticsClient

Class: AnalyticsClient

Main client for tracking analytics events.

Remarks​

The AnalyticsClient is the core class for interacting with the analytics system. It provides methods for tracking events, with built-in validation, error handling, and support for fallback to legacy endpoints.

The client supports two different endpoint formats:

  1. Modern endpoint: POST to /analytics/events with eventId in the request body
  2. Legacy endpoint: POST to /${eventId}/analytics with eventId in the URL path

The eventId represents the specific conference or event (e.g., 'aitalks26', 'fedtalks2023') that the analytics are being tracked for, not the action being performed.

While you can instantiate this class directly, it's recommended to use AnalyticsClientFactory.createClient to create properly configured instances.

Example​

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

// Create a client with a default eventId for the conference
const client = new AnalyticsClient({
  baseUrl: 'https://6xipdnwvd4.execute-api.us-east-1.amazonaws.com/dev',
  validationEndpoint: 'https://ems.prod.upgather.com/api',
  defaultEventId: 'aitalks26'
});

// Track an event - will use 'aitalks26' as the eventId
await client.trackEvent({
  metricType: MetricType.pageview,
  payload: {
    url: 'https://app.upgather.com/',
    referrer: 'https://google.com'
  }
});

Constructors​

new AnalyticsClient()​

new AnalyticsClient(config?): AnalyticsClient

Create a new AnalyticsClient.

Parameters​

config?​

AnalyticsConfig

Configuration options for the client

Returns​

AnalyticsClient

Remarks​

This constructor creates a new client with the specified configuration. It automatically creates and configures an API client and event validator.

If no configuration is provided, default values will be used.

Properties​

config​

readonly config: AnalyticsConfig

Configuration for this client instance.

Methods​

trackEvent()​

trackEvent(props): Promise<void>

Track an event using the modern endpoint.

Parameters​

props​

Partial<TrackEventProps> & Pick<TrackEventProps, "metricType" | "payload" | "organizationId">

Event properties to track

Returns​

Promise<void>

Promise that resolves when the event is successfully tracked

Remarks​

This method validates the event ID, then sends the event to the modern analytics API endpoint. It uses the POST /analytics/events format and includes the eventId in the request body.

If no eventId is provided in props but a defaultEventId was set when creating the client, the defaultEventId will be used.

If an apiKey is provided in the config, it will use the x-api-key header approach.

If validation fails, or the API request fails, an AnalyticsError is thrown.

Throws​

If the event ID is invalid or the API request fails

Example​

// With explicit eventId
await client.trackEvent({
  eventId: 'aitalks26',
  metricType: MetricType.interaction,
  payload: {
    url: 'https://app.upgather.com/dashboard',
    buttonId: 'create-new',
    timestamp: Date.now()
  }
});

// Using default eventId (if configured)
await client.trackEvent({
  metricType: MetricType.pageview,
  payload: {
    url: 'https://app.upgather.com/agenda'
  }
});

trackEventLegacy()​

trackEventLegacy(props): Promise<void>

Track an event using the legacy endpoint.

Parameters​

props​

Partial<TrackEventProps> & Pick<TrackEventProps, "metricType" | "payload" | "organizationId">

Event properties to track

Returns​

Promise<void>

Promise that resolves when the event is successfully tracked

Remarks​

This method is similar to trackEvent but uses the legacy endpoint format. It uses the POST /${eventId}/analytics format where the eventId is part of the URL path.

If no eventId is provided in props but a defaultEventId was set when creating the client, the defaultEventId will be used.

It's primarily used as a fallback when the main endpoint returns a 501 error.

Throws​

If the event ID is invalid or the API request fails

Example​

try {
  await client.trackEvent({
    metricType: MetricType.pageview,
    payload: { url: 'https://app.upgather.com/agenda' }
  });
} catch (err) {
  if (err instanceof AnalyticsError && err.statusCode === 501) {
    await client.trackEventLegacy({
      metricType: MetricType.pageview,
      payload: { url: 'https://app.upgather.com/agenda' }
    });
  } else {
    throw err;
  }
}