trackEvent

Upgather Analytics

---

Upgather Analytics / trackEvent

Function: trackEvent()

trackEvent(props, apiKeyOverride?): Promise<void>

Track an analytics event using the modern endpoint with default configuration. API key authentication is optional (used when configured).

Parameters

props

TrackEventProps

Event properties to track

apiKeyOverride?

string

Optional API key to override the cached key

Returns

Promise<void>

Promise that resolves when the event is successfully tracked

Remarks

This is the primary function for tracking events. It uses the modern /analytics/events endpoint where the eventId is included in the request body. When an API key is configured it is sent via the x-api-key header; otherwise the request is unauthenticated.

The function caches the client and API key to minimize overhead when tracking multiple events.

Example

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

// Using API key authentication
await trackEvent(
  {
    eventId: 'homepage-visit',
    metricType: MetricType.pageview,
    payload: {
      url: 'https://app.upgather.com/',
      referrer: 'https://google.com',
    },
    organizationId: 'org-example-123'
  },
  'da2-7ekeutfuafga5fqlowgydwsq2u'
);

// Or set API key once and reuse
trackEvent.setApiKey('da2-7ekeutfuafga5fqlowgydwsq2u');
await trackEvent({
  eventId: 'homepage-visit',
  metricType: MetricType.pageview,
  payload: { url: 'https://app.upgather.com/' },
  organizationId: 'org-example-123'
});

Throws

If the event is invalid or the API request fails