@mate-academy/analytics-client

Pluggable analytics client for Mate academy pages that live outside the main Next.js apps: simulators and Lovable landings. It boots sourcebuster, sends DWH events, keeps the conversionPage cookie in step with frontend / frontend-landings, and exposes the attribution readers a lead needs.

Install

npm install @mate-academy/analytics-client

Usage

import {
  createAmplitudePlugin,
  createDwhPlugin,
  getTrackingData,
  registerPlugins,
  track,
} from '@mate-academy/analytics-client';

registerPlugins([
  createDwhPlugin({ subDomain: 'ua', cookieDomain: 'mate.academy' }),
  createAmplitudePlugin({
    apiKey: process.env.AMPLITUDE_API_KEY,
    serverUrl: 'https://mate.academy/amplitude/2/httpapi',
  }),
]);

// On every page visit. The DWH plugin also records the visited page as the
// `conversionPage` cookie (or `properties.page` when the app names it).
track('page_visit', { page: window.location.pathname });

// When creating a lead: the full attribution set, same shape the DWH event carries.
const utmTags = getTrackingData({
  sourceTracker: window.sbjs,
  sessionId: getCookieValue('_mate-user-session-id'),
});

Calls made before registerPlugins are queued and replayed once the plugins are initialised. A plugin that throws does not stop the others. The Amplitude plugin flushes pending events over sendBeacon when the page is hidden; serverUrl routes them through the mate.academy proxy, as the main apps do.

Custom plugins

Extend AnalyticsPlugin and override the hooks you need:

import { AnalyticsPlugin, type TrackPayload } from '@mate-academy/analytics-client';

class ConsolePlugin extends AnalyticsPlugin {
  readonly name = 'console';

  track({ event, properties }: TrackPayload): void {
    console.log(event, properties);
  }
}

Attribution readers

| Function | Returns | |---|---| | getTrackingData({ sourceTracker, sessionId }) | source data, click ids, conversionPage, ip, session, user agent | | getSourceData(sourceTracker) | fvPage, lvPage and the lv* campaign fields | | getClickIds() | gclid, gbraid, wbraid, gClientid, fbc, fbp, fbclid, ttclid, sdclid, ksclid | | getConversionPage() / updateConversionPage(options) | the conversionPage cookie |

Development

pnpm install     # also refreshes pnpm-lock.yaml
pnpm run lint
pnpm run type-check
pnpm test
pnpm run build    # bundles src/ into dist/ with tsup

Run the publish contract exactly as CI does before opening a pull request:

./matectl packages-publish verify mate-analytics

Releasing is a version bump in the pull request; CI publishes on merge once that version is absent from the registry.