@mate-academy/analytics-client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { Types } from '@amplitude/analytics-browser';
+
+interface AnalyticsPlugin {
+    name: string;
+    init?(): void;
+    track(payload: {
+        event: string;
+        properties: Record<string, unknown>;
+    }): void;
+    identify?(userId: string, traits?: Record<string, unknown>): void;
+    reset?(): void;
+}
+
+declare function registerPlugins(newPlugins: AnalyticsPlugin[]): void;
+declare function track(event: string, properties?: Record<string, unknown>): void;
+declare function identify(userId: string, traits?: Record<string, unknown>): void;
+declare function reset(): void;
+
+interface DwhErrorContext {
+    eventType: string;
+    eventProperties: Record<string, unknown>;
+    attempts: number;
+}
+interface DwhPluginOptions {
+    subDomain?: string;
+    dwhEndpoint?: string;
+    cookieDomain?: string;
+    onError?: (error: unknown, context: DwhErrorContext) => void;
+}
+declare function createDwhPlugin(options?: DwhPluginOptions): AnalyticsPlugin;
+
+interface AmplitudePluginOptions {
+    apiKey: string;
+    config?: Partial<Types.BrowserOptions>;
+}
+declare function createAmplitudePlugin(options: AmplitudePluginOptions): AnalyticsPlugin;
+
+declare const PLUGIN_NAMES: {
+    readonly DWH: "dwh";
+    readonly AMPLITUDE: "amplitude";
+};
+type PluginName = typeof PLUGIN_NAMES[keyof typeof PLUGIN_NAMES];
+
+export { type AnalyticsPlugin, type DwhErrorContext, PLUGIN_NAMES, type PluginName, createAmplitudePlugin, createDwhPlugin, identify, registerPlugins, reset, track };

package/dist/index.js

@@ -0,0 +1,409 @@
+// src/tracker.ts
+var plugins = [];
+var isInitialized = false;
+var queue = [];
+function safeCall(plugin, fn) {
+  try {
+    fn();
+  } catch (error) {
+    console.error(`[analytics] plugin "${plugin.name}" failed:`, error);
+  }
+}
+function dispatch(call) {
+  plugins.forEach((plugin) => {
+    safeCall(plugin, () => {
+      if (call.type === "track") {
+        plugin.track({ event: call.event, properties: call.properties });
+      } else if (call.type === "identify") {
+        plugin.identify?.(call.userId, call.traits);
+      } else if (call.type === "reset") {
+        plugin.reset?.();
+      }
+    });
+  });
+}
+function registerPlugins(newPlugins) {
+  plugins = newPlugins;
+  plugins.forEach((plugin) => {
+    safeCall(plugin, () => plugin.init?.());
+  });
+  isInitialized = true;
+  while (queue.length > 0) {
+    const call = queue.shift();
+    if (call) {
+      dispatch(call);
+    }
+  }
+}
+function track(event, properties = {}) {
+  if (!isInitialized) {
+    queue.push({ type: "track", event, properties });
+    return;
+  }
+  dispatch({ type: "track", event, properties });
+}
+function identify(userId, traits) {
+  if (!isInitialized) {
+    queue.push({ type: "identify", userId, traits });
+    return;
+  }
+  dispatch({ type: "identify", userId, traits });
+}
+function reset() {
+  if (!isInitialized) {
+    queue.push({ type: "reset" });
+    return;
+  }
+  dispatch({ type: "reset" });
+}
+
+// src/plugins/dwh.ts
+import sbjs from "@mate-academy/sourcebuster";
+
+// src/cookies.ts
+import { parse } from "cookie";
+function getCookieValue(name) {
+  try {
+    return parse(document.cookie)[name] ?? null;
+  } catch {
+    return null;
+  }
+}
+function setCookie(name, value, maxAge) {
+  document.cookie = `${name}=${value}; path=/; max-age=${maxAge}`;
+}
+
+// src/device-id.ts
+var USER_DEVICE_ID_KEY = "_mate-user-device-id";
+function base64Id() {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  let result = "";
+  for (let index = 0; index < 22; index += 1) {
+    result += chars.charAt(Math.floor(Math.random() * 64));
+  }
+  return result;
+}
+function getOrCreateDeviceId() {
+  const fromCookie = getCookieValue(USER_DEVICE_ID_KEY);
+  if (fromCookie) {
+    try {
+      localStorage.setItem(USER_DEVICE_ID_KEY, fromCookie);
+    } catch {
+    }
+    return fromCookie;
+  }
+  let fromStorage = null;
+  try {
+    fromStorage = localStorage.getItem(USER_DEVICE_ID_KEY);
+  } catch {
+  }
+  if (fromStorage) {
+    setCookie(USER_DEVICE_ID_KEY, fromStorage, 31536e3);
+    return fromStorage;
+  }
+  const deviceId = base64Id();
+  try {
+    localStorage.setItem(USER_DEVICE_ID_KEY, deviceId);
+  } catch {
+  }
+  setCookie(USER_DEVICE_ID_KEY, deviceId, 31536e3);
+  return deviceId;
+}
+
+// src/constants.ts
+var PLUGIN_NAMES = {
+  DWH: "dwh",
+  AMPLITUDE: "amplitude"
+};
+
+// src/plugins/dwh.ts
+var USER_ANALYTICS_ID_KEY = "_mate-user-analytics-id";
+var USER_SESSION_ID_KEY = "_mate-user-session-id";
+var SESSION_MAX_AGE_SECONDS = 1800;
+var MAX_SEND_ATTEMPTS = 3;
+function createDwhPlugin(options = {}) {
+  const subDomain = options.subDomain ?? "ua";
+  const dwhEndpoint = options.dwhEndpoint ?? "/dwh";
+  const cookieDomain = options.cookieDomain ?? "mate.academy";
+  const onError = options.onError;
+  let sourceTracker;
+  function getUserIp() {
+    return getCookieValue("_mate-user-ip") || "8.8.8.8";
+  }
+  function getUserId() {
+    let fromStorage = null;
+    try {
+      fromStorage = localStorage.getItem(USER_ANALYTICS_ID_KEY);
+    } catch {
+    }
+    if (fromStorage) {
+      setCookie(USER_ANALYTICS_ID_KEY, fromStorage, 31536e3);
+      return fromStorage;
+    }
+    const fromCookie = getCookieValue(USER_ANALYTICS_ID_KEY);
+    if (fromCookie) {
+      try {
+        localStorage.setItem(USER_ANALYTICS_ID_KEY, fromCookie);
+      } catch {
+      }
+      return fromCookie;
+    }
+    return null;
+  }
+  function ensureSessionId() {
+    const sourceTrackerSessionId = sourceTracker?.get?.session?.sid;
+    const currentSessionId = getCookieValue(USER_SESSION_ID_KEY);
+    const isSessionChanged = sourceTrackerSessionId && currentSessionId && Number(sourceTrackerSessionId) > Number(currentSessionId);
+    const shouldSetNewSessionId = !currentSessionId || isSessionChanged;
+    if (shouldSetNewSessionId) {
+      const sessionId = Date.now().toString();
+      setCookie(USER_SESSION_ID_KEY, sessionId, SESSION_MAX_AGE_SECONDS);
+      return { sessionId, isNewSession: true };
+    }
+    setCookie(USER_SESSION_ID_KEY, currentSessionId, SESSION_MAX_AGE_SECONDS);
+    return { sessionId: currentSessionId, isNewSession: false };
+  }
+  function getFirstVisitPage() {
+    if (!sourceTracker) {
+      return null;
+    }
+    const entrancePoint = sourceTracker.get.first_add.ep;
+    if (!entrancePoint) {
+      return null;
+    }
+    try {
+      const pathname = new URL(entrancePoint).pathname.slice(1);
+      return pathname || "home";
+    } catch {
+      return entrancePoint;
+    }
+  }
+  function getSourceData() {
+    if (!sourceTracker) {
+      return {
+        fvPage: null,
+        lvType: null,
+        lvSource: null,
+        lvMedium: null,
+        lvCampaign: null,
+        lvContent: null,
+        lvTerm: null,
+        lvAccountId: null,
+        lvCampaignId: null,
+        lvAdGroupId: null,
+        lvAdId: null,
+        lvTermId: null
+      };
+    }
+    const current = sourceTracker.get.current;
+    return {
+      fvPage: getFirstVisitPage(),
+      lvType: current.typ,
+      lvSource: current.src,
+      lvMedium: current.mdm,
+      lvCampaign: current.cmp,
+      lvContent: current.cnt,
+      lvTerm: current.trm,
+      lvAccountId: current.ac_id,
+      lvCampaignId: current.cmp_id,
+      lvAdGroupId: current.adg_id,
+      lvAdId: current.ad_id,
+      lvTermId: current.trm_id
+    };
+  }
+  function getFacebookParams() {
+    const fbp = getCookieValue("_fbp");
+    let fbc = getCookieValue("_fbc");
+    let fbclid = getCookieValue("_mate-fbclid");
+    if (fbclid?.includes("https://")) {
+      const queryParamsString = fbclid.split("?")[1];
+      const queryParams = new URLSearchParams(queryParamsString);
+      fbclid = queryParams.get("fbclid") ?? null;
+    }
+    if (!fbc && fbclid) {
+      fbc = `fb.1.${Date.now()}.${fbclid}`;
+    }
+    if (fbc?.includes("https://")) {
+      const queryParamsString = fbc.split("?")[1];
+      const fbcTimestamp = fbc.split(".")[2] ?? Date.now().toString();
+      const queryParams = new URLSearchParams(queryParamsString);
+      fbclid = queryParams.get("fbclid") ?? null;
+      fbc = `fb.1.${fbcTimestamp}.${fbclid}`;
+    }
+    return { fbp, fbc, fbclid };
+  }
+  function getClickIds() {
+    const facebookParams = getFacebookParams();
+    return {
+      gclid: getCookieValue("_mate-gclid"),
+      gbraid: getCookieValue("_mate-gbraid"),
+      wbraid: getCookieValue("_mate-wbraid"),
+      gClientid: getCookieValue("_ga") ?? "0.0",
+      fbc: facebookParams.fbc,
+      fbp: facebookParams.fbp,
+      fbclid: facebookParams.fbclid,
+      ttclid: getCookieValue("_mate-ttclid"),
+      sdclid: getCookieValue("_mate-sdclid"),
+      ksclid: getCookieValue("_mate-ksclid")
+    };
+  }
+  function getTrackingData(sessionId) {
+    return {
+      ...getSourceData(),
+      ...getClickIds(),
+      locationIpAddress: getUserIp(),
+      sessionId,
+      userAgent: sourceTracker ? sourceTracker.get.udata.uag : navigator.userAgent
+    };
+  }
+  function sleep(ms) {
+    return new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+  async function sendPayload(payload) {
+    const body = JSON.stringify(payload);
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([body], { type: "application/json" });
+      const scheduled = navigator.sendBeacon(dwhEndpoint, blob);
+      if (scheduled) {
+        return;
+      }
+    }
+    const response = await fetch(dwhEndpoint, {
+      method: "POST",
+      body,
+      credentials: "omit",
+      keepalive: true,
+      headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+      throw new Error(`DWH response not ok: ${response.statusText}`);
+    }
+  }
+  async function sendDwhEvent(eventType, eventProperties, attempt = 1) {
+    try {
+      const { sessionId, isNewSession } = ensureSessionId();
+      const userId = getUserId();
+      const deviceId = getOrCreateDeviceId();
+      const tracking = getTrackingData(sessionId);
+      const basePayload = {
+        session_id: sessionId,
+        platform_user_id: userId,
+        platform_device_id: deviceId,
+        ...tracking
+      };
+      if (isNewSession) {
+        await sendPayload({
+          event_type: "session_start",
+          location: window.location.pathname,
+          event_properties: { subDomain },
+          ...basePayload
+        });
+      }
+      await sendPayload({
+        event_type: eventType,
+        location: window.location.pathname,
+        event_properties: {
+          subDomain,
+          ...eventProperties
+        },
+        ...basePayload
+      });
+    } catch (error) {
+      if (attempt < MAX_SEND_ATTEMPTS) {
+        const delayTime = 100 * 2 ** (attempt - 1);
+        await sleep(delayTime);
+        return sendDwhEvent(eventType, eventProperties, attempt + 1);
+      }
+      onError?.(error, {
+        eventType,
+        eventProperties,
+        attempts: attempt
+      });
+    }
+  }
+  return {
+    name: PLUGIN_NAMES.DWH,
+    init() {
+      sourceTracker = window.sbjs || sbjs;
+      if (sourceTracker !== window.sbjs) {
+        sourceTracker.init({
+          domain: cookieDomain,
+          user_ip: getUserIp()
+        });
+        window.sbjs = sourceTracker;
+      }
+    },
+    track({ event, properties }) {
+      sendDwhEvent(event, properties);
+    },
+    reset() {
+      try {
+        localStorage.removeItem(USER_ANALYTICS_ID_KEY);
+      } catch {
+      }
+      setCookie(USER_ANALYTICS_ID_KEY, "", 0);
+      setCookie(USER_SESSION_ID_KEY, "", 0);
+    }
+  };
+}
+
+// src/plugins/amplitude.ts
+import { createInstance, Identify } from "@amplitude/analytics-browser";
+function createAmplitudePlugin(options) {
+  let client = null;
+  return {
+    name: PLUGIN_NAMES.AMPLITUDE,
+    init() {
+      client = createInstance();
+      const deviceId = getOrCreateDeviceId();
+      client.init(options.apiKey, {
+        deviceId,
+        autocapture: {
+          attribution: false,
+          pageViews: false,
+          sessions: false,
+          fileDownloads: false,
+          formInteractions: false
+        },
+        identityStorage: "localStorage",
+        ...options.config
+      });
+    },
+    track({ event, properties }) {
+      if (!client) {
+        return;
+      }
+      client.track(event, properties);
+    },
+    identify(userId, traits) {
+      if (!client) {
+        return;
+      }
+      client.setUserId(userId);
+      if (traits) {
+        const userProperties = new Identify();
+        Object.entries(traits).forEach(([key, value]) => {
+          userProperties.set(key, value);
+        });
+        client.identify(userProperties);
+      }
+    },
+    reset() {
+      if (!client) {
+        return;
+      }
+      client.reset();
+    }
+  };
+}
+export {
+  PLUGIN_NAMES,
+  createAmplitudePlugin,
+  createDwhPlugin,
+  identify,
+  registerPlugins,
+  reset,
+  track
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mate-academy/analytics-client",
+  "version": "1.0.0",
+  "description": "Pluggable analytics client for Mate academy external pages",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@amplitude/analytics-browser": "^2.40.0",
+    "@mate-academy/sourcebuster": "^1.5.0",
+    "cookie": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/cookie": "^0.6.0",
+    "@typescript-eslint/parser": "^8.58.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mate-academy/website.git",
+    "directory": "packages/mate-analytics"
+  },
+  "license": "MIT"
+}