@gem-sdk/clarity-js 0.8.94

package/src/custom/dialog.ts

@@ -0,0 +1,69 @@
+import { Constant, NodeInfo } from "@clarity-types/layout";
+
+/**
+ * Custom module for tracking HTML Dialog elements
+ * Handles detection of modal vs non-modal dialogs for proper visualization
+ */
+
+export interface DialogTrackingResult {
+    attributes: { [key: string]: string };
+    isModal: boolean;
+}
+
+/**
+ * Tracks dialog element state and determines if it's a modal dialog
+ * Modal dialogs are opened via showModal() and rendered in the browser's top-layer
+ *
+ * @param dialogElement - The dialog element to track
+ * @param attributes - Current attributes of the dialog
+ * @returns Tracking result with updated attributes and modal state
+ */
+export function trackDialog(
+    dialogElement: HTMLDialogElement,
+    attributes: { [key: string]: string }
+): DialogTrackingResult {
+    const result: DialogTrackingResult = {
+        attributes: { ...attributes },
+        isModal: false
+    };
+
+    // Capture the open attribute which indicates if dialog is currently shown
+    if (dialogElement.open) {
+        result.attributes["open"] = "";
+    }
+
+    // Detect if this is a modal dialog by checking for ::backdrop pseudo-element
+    // Modal dialogs shown via showModal() have a backdrop, non-modal dialogs don't
+    if (dialogElement.open) {
+        try {
+            const backdropStyle = window.getComputedStyle(dialogElement, "::backdrop");
+            const backdropDisplay = backdropStyle.getPropertyValue("display");
+
+            // Modal dialogs have ::backdrop with display !== 'none'
+            if (backdropDisplay && backdropDisplay !== "none") {
+                result.isModal = true;
+                result.attributes[Constant.GXDialogModal] = "true";
+            }
+        } catch (e) {
+            // If we can't check for backdrop (older browsers),
+            // we can't reliably detect modal state
+            console.warn("Error detecting modal dialog:", e);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Creates dialog node data for tracking
+ *
+ * @param tag - Tag name (should be "DIALOG")
+ * @param attributes - Dialog attributes
+ * @returns NodeInfo object ready for tracking
+ */
+export function createDialogNodeData(
+    tag: string,
+    attributes: { [key: string]: string }
+): NodeInfo {
+    return { tag, attributes };
+}

package/src/custom/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Custom modules for GemX Clarity extensions
+ * Contains custom tracking and rendering logic that extends the base Clarity functionality
+ */
+
+export * from "./dialog";

package/src/data/baseline.ts

@@ -0,0 +1,162 @@
+import { Event, BooleanFlag } from "@clarity-types/data";
+import { BaselineData, BaselineState } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import encode from "@src/data/encode";
+
+export let state: BaselineState = null;
+let buffer: BaselineData = null;
+let update: boolean = false;
+
+export function start(): void {
+    update = false;
+    reset();
+}
+
+export function reset(): void {
+    // Baseline state holds the previous values - if it is updated in the current payload,
+    // reset the state to current value after sending the previous state
+    if (update) {
+        state = { time: time(), event: Event.Baseline, data: {
+            visible: buffer.visible,
+            docWidth: buffer.docWidth,
+            docHeight: buffer.docHeight,
+            screenWidth: buffer.screenWidth,
+            screenHeight: buffer.screenHeight,
+            scrollX: buffer.scrollX,
+            scrollY: buffer.scrollY,
+            pointerX: buffer.pointerX,
+            pointerY: buffer.pointerY,
+            activityTime: buffer.activityTime,
+            scrollTime: buffer.scrollTime,
+            pointerTime: buffer.pointerTime,
+            moveX: buffer.moveX,
+            moveY: buffer.moveY,
+            moveTime: buffer.moveTime,
+            downX: buffer.downX,
+            downY: buffer.downY,
+            downTime: buffer.downTime,
+            upX: buffer.upX,
+            upY: buffer.upY,
+            upTime: buffer.upTime,
+            pointerPrevX: buffer.pointerPrevX,
+            pointerPrevY: buffer.pointerPrevY,
+            pointerPrevTime: buffer.pointerPrevTime,
+            modules: buffer.modules,
+          }
+        };
+    }
+    buffer = buffer ? buffer : {
+        visible: BooleanFlag.True,
+        docWidth: 0,
+        docHeight: 0,
+        screenWidth: 0,
+        screenHeight: 0,
+        scrollX: 0,
+        scrollY: 0,
+        pointerX: 0,
+        pointerY: 0,
+        activityTime: 0,
+        scrollTime: 0,
+        pointerTime: undefined,
+        moveX: undefined,
+        moveY: undefined,
+        moveTime: undefined,
+        downX: undefined,
+        downY: undefined,
+        downTime: undefined,
+        upX: undefined,
+        upY: undefined,
+        upTime: undefined,
+        pointerPrevX: undefined,
+        pointerPrevY: undefined,
+        pointerPrevTime: undefined,
+        modules: null,
+    };
+}
+
+export function track(event: Event, x: number, y: number, time?: number): void {
+    switch (event) {
+        case Event.Document:
+            buffer.docWidth = x;
+            buffer.docHeight = y;
+            break;
+        case Event.Resize:
+            buffer.screenWidth = x;
+            buffer.screenHeight = y;
+            break;
+        case Event.Scroll:
+            buffer.scrollX = x;
+            buffer.scrollY = y;
+            buffer.scrollTime = time;
+            break;
+        case Event.MouseMove:
+            buffer.moveX = x;
+            buffer.moveY = y;
+            buffer.moveTime = time;
+            buffer.pointerPrevX = buffer.pointerX;
+            buffer.pointerPrevY = buffer.pointerY;
+            buffer.pointerPrevTime = buffer.pointerTime;
+            buffer.pointerX = x;
+            buffer.pointerY = y;
+            buffer.pointerTime = time;
+            break;
+        case Event.MouseDown:
+            buffer.downX = x;
+            buffer.downY = y;
+            buffer.downTime = time;
+            buffer.pointerPrevX = buffer.pointerX;
+            buffer.pointerPrevY = buffer.pointerY;
+            buffer.pointerPrevTime = buffer.pointerTime;
+            buffer.pointerX = x;
+            buffer.pointerY = y;
+            buffer.pointerTime = time;
+            break;
+        case Event.MouseUp:
+            buffer.upX = x;
+            buffer.upY = y;
+            buffer.upTime = time;
+            buffer.pointerPrevX = buffer.pointerX;
+            buffer.pointerPrevY = buffer.pointerY;
+            buffer.pointerPrevTime = buffer.pointerTime;
+            buffer.pointerX = x;
+            buffer.pointerY = y;
+            buffer.pointerTime = time;
+            break;
+        default:
+            buffer.pointerPrevX = buffer.pointerX;
+            buffer.pointerPrevY = buffer.pointerY;
+            buffer.pointerPrevTime = buffer.pointerTime;
+            buffer.pointerX = x;
+            buffer.pointerY = y;
+            buffer.pointerTime = time;
+            break;
+    }
+    update = true;
+}
+
+export function activity(t: number): void {
+    buffer.activityTime = t;
+}
+
+export function visibility(t: number, visible: BooleanFlag): void {
+    buffer.visible = visible;
+    if (!buffer.visible) {
+        activity(t);
+    }
+    update = true;
+}
+
+export function dynamic(modules: Set<number>): void {
+    buffer.modules = Array.from(modules);
+    update = true;
+}
+
+export function compute(): void {
+    if (update) {
+        encode(Event.Baseline);
+    }
+}
+
+export function stop(): void {
+    reset();
+}

package/src/data/compress.ts

@@ -0,0 +1,31 @@
+import { Constant } from "@clarity-types/data";
+
+const supported = Constant.CompressionStream in window;
+
+export default async function(input: string): Promise<Uint8Array> {
+    try {
+        if (supported) {
+            // Create a readable stream from given input string and
+            // pipe it through text encoder and compression stream to gzip it
+            const stream = new ReadableStream({async start(controller) {
+                controller.enqueue(input);
+                controller.close();
+            }}).pipeThrough(new TextEncoderStream()).pipeThrough(new window[Constant.CompressionStream]("gzip"));
+            return new Uint8Array(await read(stream));
+        }
+    } catch { /* do nothing */ }
+    return null;
+}
+
+async function read(stream: ReadableStream): Promise<number[]> {
+    const reader = stream.getReader();
+    const chunks:number[] = [];
+    let done = false;
+    let value: number[] = [];
+    while (!done) {
+      ({ done, value } = await reader.read());
+      if (done) { return chunks; }
+      chunks.push(...value);
+    }
+    return chunks;
+}

package/src/data/consent.ts

@@ -0,0 +1,84 @@
+import { ConsentData, ConsentSource, ConsentState, ConsentType, Constant, Dimension, Event, GCMConsent, GCMConsentState } from "@clarity-types/data";
+import * as dimension from "@src/data/dimension";
+import encode from "./encode";
+import { consentv2 } from "@src/data/metadata";
+import coreConfig from "@src/core/config";
+
+export let data: ConsentData = null;
+let updateConsent: boolean = true;
+
+export function start(): void {
+    const ics = window.google_tag_data?.ics;
+    updateConsent = true;
+    if (ics?.addListener) {
+        ics.addListener(
+            [Constant.AdStorage, Constant.AnalyticsStorage],
+            processConsent
+        );
+    }
+}
+
+export function stop(): void {
+    updateConsent = true;
+}
+
+function processConsent(): void {
+    const ics = window.google_tag_data?.ics;
+    if (!ics?.getConsentState) {
+        return;
+    }
+
+    try {
+        const analytics_storage = ics.getConsentState(Constant.AnalyticsStorage);
+        const ad_storage = ics.getConsentState(Constant.AdStorage);
+        const consentState = getGcmConsentState({ ad_Storage: ad_storage, analytics_Storage: analytics_storage });
+        consentv2(consentState);
+    } catch {
+        // Handle GTM errors gracefully (e.g., misconfigured consent initialization)
+        return;
+    }
+}
+
+function getGcmConsentState(googleConsent: GCMConsentState): ConsentState {
+    const consentState: ConsentState = {
+        source: ConsentSource.GCM,
+        ad_Storage: googleConsent.ad_Storage === GCMConsent.Granted ? Constant.Granted : Constant.Denied,
+        analytics_Storage: googleConsent.analytics_Storage === GCMConsent.Granted ? Constant.Granted : Constant.Denied,
+    };
+
+    return consentState;
+}
+
+
+export function config(consent: ConsentData): void {
+    trackConsent(consent.analytics_Storage ? ConsentType.Implicit : ConsentType.None);
+    data = consent;
+}
+
+// When we get consent signal as false, we restart the service and track config as false.
+export function consent(): void {
+    trackConsent(ConsentType.General);
+}
+
+function trackConsent(consent: ConsentType): void {
+    dimension.log(Dimension.Consent, consent.toString());
+}
+
+export function trackConsentv2(consent: ConsentData): void {
+    data = consent;
+    encode(Event.Consent);
+}
+
+// Compute function is called every upload, but we only want to send consent data once.
+export function compute(): void {
+    if (updateConsent) {
+        encode(Event.Consent);
+        updateConsent = false;
+        if (!coreConfig.track) {
+            const ics = window.google_tag_data?.ics;
+            if (ics?.usedUpdate) {
+                processConsent();
+            }
+        }
+    }
+}

package/src/data/cookie.ts

@@ -0,0 +1,90 @@
+import { Constant } from "@clarity-types/data";
+import config from "@src/core/config";
+import { decodeCookieValue, encodeCookieValue, supported } from "@src/data/util";
+
+let rootDomain = null;
+export const COOKIE_SEP = Constant.Caret;
+
+export function start() {
+  rootDomain = null;
+}
+
+export function stop() {
+  rootDomain = null;
+}
+
+export function getCookie(key: string, limit = false): string {
+  if (supported(document, Constant.Cookie)) {
+    let cookies: string[] = document.cookie.split(Constant.Semicolon);
+    if (cookies) {
+      for (let i = 0; i < cookies.length; i++) {
+        let pair: string[] = cookies[i].split(Constant.Equals);
+        if (pair.length > 1 && pair[0] && pair[0].trim() === key) {
+          // Some browsers automatically url encode cookie values if they are not url encoded.
+          // We therefore encode and decode cookie values ourselves.
+          // For backwards compatability we need to consider 3 cases:
+          // * Cookie was previously not encoded by Clarity and browser did not encode it
+          // * Cookie was previously not encoded by Clarity and browser encoded it once or more
+          // * Cookie was previously encoded by Clarity and browser did not encode it
+          let [isEncoded, decodedValue] = decodeCookieValue(pair[1]);
+
+          while (isEncoded) {
+            [isEncoded, decodedValue] = decodeCookieValue(decodedValue);
+          }
+
+          // If we are limiting cookies, check if the cookie value is limited
+          if (limit) {
+            return decodedValue.endsWith(`${Constant.Tilde}1`) ? decodedValue.substring(0, decodedValue.length - 2) : null;
+          }
+
+          return decodedValue;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+export function setCookie(key: string, value: string, time: number): void {
+  // only write cookies if we are currently in a cookie writing mode (and they are supported)
+  // OR if we are trying to write an empty cookie (i.e. clear the cookie value out)
+  if ((config.track || value == Constant.Empty) && ((navigator && navigator.cookieEnabled) || supported(document, Constant.Cookie))) {
+    // Some browsers automatically url encode cookie values if they are not url encoded.
+    // We therefore encode and decode cookie values ourselves.
+    let encodedValue = encodeCookieValue(value);
+
+    let expiry = new Date();
+    expiry.setDate(expiry.getDate() + time);
+    let expires = expiry ? Constant.Expires + expiry.toUTCString() : Constant.Empty;
+    let cookie = `${key}=${encodedValue}${Constant.Semicolon}${expires}${Constant.Path}`;
+    try {
+      // Attempt to get the root domain only once and fall back to writing cookie on the current domain.
+      if (rootDomain === null) {
+        let hostname = location.hostname ? location.hostname.split(Constant.Dot) : [];
+        // Walk backwards on a domain and attempt to set a cookie, until successful
+        for (let i = hostname.length - 1; i >= 0; i--) {
+          rootDomain = `.${hostname[i]}${rootDomain ? rootDomain : Constant.Empty}`;
+          // We do not wish to attempt writing a cookie on the absolute last part of the domain, e.g. .com or .net.
+          // So we start attempting after second-last part, e.g. .domain.com (PASS) or .co.uk (FAIL)
+          if (i < hostname.length - 1) {
+            // Write the cookie on the current computed top level domain
+            document.cookie = `${cookie}${Constant.Semicolon}${Constant.Domain}${rootDomain}`;
+            // Once written, check if the cookie exists and its value matches exactly with what we intended to set
+            // Checking for exact value match helps us eliminate a corner case where the cookie may already be present with a different value
+            // If the check is successful, no more action is required and we can return from the function since rootDomain cookie is already set
+            // If the check fails, continue with the for loop until we can successfully set and verify the cookie
+            if (getCookie(key) === value) {
+              return;
+            }
+          }
+        }
+        // Finally, if we were not successful and gone through all the options, play it safe and reset rootDomain to be empty
+        // This forces our code to fall back to always writing cookie to the current domain
+        rootDomain = Constant.Empty;
+      }
+    } catch {
+      rootDomain = Constant.Empty;
+    }
+    document.cookie = rootDomain ? `${cookie}${Constant.Semicolon}${Constant.Domain}${rootDomain}` : cookie;
+  }
+}

package/src/data/custom.ts

@@ -0,0 +1,23 @@
+import { Constant, CustomData, Event } from "@clarity-types/data";
+import * as core from "@src/core";
+import encode from "./encode";
+
+export let data: CustomData = null;
+
+// custom events allow 2 parameters or 1 parameter to be passed. If 2 are passed we
+// consider it a key value pair. If only 1 is passed we only consider the event to have a value.
+export function event(a: string, b: string): void {
+    if (core.active() &&
+        a &&
+        typeof a === Constant.String &&
+        a.length < 255
+        ) {
+            if (b && typeof b === Constant.String && b.length < 255) {
+                data = { key: a, value: b};
+            } else {
+                data = { value: a }
+            }
+            encode(Event.Custom);
+        
+    }
+}

package/src/data/dimension.ts

@@ -0,0 +1,53 @@
+import { Check, Event, Dimension, DimensionData, Setting } from "@clarity-types/data";
+import * as limit from "@src/data/limit";
+import encode from "./encode";
+
+export let data: DimensionData = null;
+export let updates: DimensionData = null;
+let limited = false;
+
+export function start(): void {
+    data = {};
+    updates = {};
+    limited = false;
+}
+
+export function stop(): void {
+    data = {};
+    updates = {};
+    limited = false;
+}
+
+export function log(dimension: Dimension, value: string): void {
+    // Check valid value before moving ahead
+    if (value) {
+        // Ensure received value is casted into a string if it wasn't a string to begin with
+        value = `${value}`;
+        if (!(dimension in data)) { data[dimension] = []; }
+        if (data[dimension].indexOf(value) < 0) {
+            // Limit check to ensure we have a cap on number of dimensions we can collect
+            if (data[dimension].length > Setting.CollectionLimit) {
+                if (!limited) {
+                    limited = true;
+                    limit.trigger(Check.Collection);
+                }
+                return;
+            }
+
+            data[dimension].push(value);
+            // If this is a new value, track it as part of updates object
+            // This allows us to only send back new values in subsequent payloads
+            if (!(dimension in updates)) { updates[dimension] = []; }
+            updates[dimension].push(value);
+        }
+    }
+}
+
+export function compute(): void {
+    encode(Event.Dimension);
+}
+
+export function reset(): void {
+    updates = {};
+    limited = false;
+}

package/src/data/encode.ts

@@ -0,0 +1,155 @@
+import { Event, Token } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import * as baseline from "@src/data/baseline";
+import * as consent from "@src/data/consent";
+import * as custom from "@src/data/custom";
+import * as dimension from "@src/data/dimension";
+import * as limit from "@src/data/limit";
+import * as metric from "@src/data/metric";
+import * as ping from "@src/data/ping";
+import * as summary from "@src/data/summary";
+import * as upgrade from "@src/data/upgrade";
+import * as variable from "@src/data/variable";
+import * as extract from "@src/data/extract";
+import { queue, track } from "./upload";
+
+export default function (event: Event): void {
+    const t = time();
+    let tokens: Token[] = [t, event];
+    switch (event) {
+        case Event.Baseline: {
+            const b = baseline.state;
+            if (b && b.data) {
+                tokens = [b.time, b.event];
+                tokens.push(b.data.visible);
+                tokens.push(b.data.docWidth);
+                tokens.push(b.data.docHeight);
+                tokens.push(b.data.screenWidth);
+                tokens.push(b.data.screenHeight);
+                tokens.push(b.data.scrollX);
+                tokens.push(b.data.scrollY);
+                tokens.push(b.data.pointerX);
+                tokens.push(b.data.pointerY);
+                tokens.push(b.data.activityTime);
+                tokens.push(b.data.scrollTime);
+                tokens.push(b.data.pointerTime);
+                tokens.push(b.data.moveX);
+                tokens.push(b.data.moveY);
+                tokens.push(b.data.moveTime);
+                tokens.push(b.data.downX);
+                tokens.push(b.data.downY);
+                tokens.push(b.data.downTime);
+                tokens.push(b.data.upX);
+                tokens.push(b.data.upY);
+                tokens.push(b.data.upTime);
+                tokens.push(b.data.pointerPrevX);
+                tokens.push(b.data.pointerPrevY);
+                tokens.push(b.data.pointerPrevTime);
+                tokens.push(b.data.modules);
+                queue(tokens, false);
+            }
+            baseline.reset();
+            break;
+        }
+        case Event.Ping:
+            tokens.push(ping.data.gap);
+            queue(tokens);
+            break;
+        case Event.Limit:
+            tokens.push(limit.data.check);
+            queue(tokens, false);
+            break;
+        case Event.Upgrade:
+            tokens.push(upgrade.data.key);
+            queue(tokens);
+            break;
+        case Event.Upload:
+            tokens.push(track.sequence);
+            tokens.push(track.attempts);
+            tokens.push(track.status);
+            queue(tokens, false);
+            break;
+        case Event.Custom:
+            // not all custom events have a key - if it wasn't passed server handles just value
+            custom.data.key && tokens.push(custom.data.key);
+            tokens.push(custom.data.value);
+            queue(tokens);
+            break;
+        case Event.Variable: {
+            const variableKeys = Object.keys(variable.data);
+            if (variableKeys.length > 0) {
+                for (const v of variableKeys) {
+                    tokens.push(v);
+                    tokens.push(variable.data[v]);
+                }
+                variable.reset();
+                queue(tokens, false);
+            }
+            break;
+        }
+        case Event.Metric: {
+            const metricKeys = Object.keys(metric.updates);
+            if (metricKeys.length > 0) {
+                for (const m of metricKeys) {
+                    const key = parseInt(m, 10);
+                    tokens.push(key);
+                    // For computation, we need microseconds precision that performance.now() API offers
+                    // However, for data over the wire, we round it off to milliseconds precision.
+                    tokens.push(Math.round(metric.updates[m]));
+                }
+                metric.reset();
+                queue(tokens, false);
+            }
+            break;
+        }
+        case Event.Dimension: {
+            const dimensionKeys = Object.keys(dimension.updates);
+            if (dimensionKeys.length > 0) {
+                for (const d of dimensionKeys) {
+                    const key = parseInt(d, 10);
+                    tokens.push(key);
+                    tokens.push(dimension.updates[d]);
+                }
+                dimension.reset();
+                queue(tokens, false);
+            }
+            break;
+        }
+        case Event.Summary: {
+            const eventKeys = Object.keys(summary.data);
+            if (eventKeys.length > 0) {
+                for (const e of eventKeys) {
+                    const key = parseInt(e, 10);
+                    tokens.push(key);
+                    tokens.push([].concat(...summary.data[e]));
+                }
+                summary.reset();
+                queue(tokens, false);
+            }
+            break;
+        }
+        case Event.Extract: {
+            const extractKeys = extract.keys;
+            extractKeys.forEach(e => {
+                tokens.push(e);
+                const token = []
+                for (const d in extract.data[e]) {
+                    const key = parseInt(d, 10);
+                    token.push(key);
+                    token.push(extract.data[e][d]);
+                }
+                tokens.push(token);
+            });
+
+            extract.reset();
+            queue(tokens, false);
+            break;
+        }
+        case Event.Consent:
+            tokens.push(consent.data.source);
+            tokens.push(consent.data.ad_Storage);
+            tokens.push(consent.data.analytics_Storage);
+            queue(tokens, false);
+            break;
+    }
+}