📦 Installation

NPM

npm install @appsurify-testmap/google-custom-event-tracker

Yarn

yarn add @appsurify-testmap/google-custom-event-tracker

PNPM

pnpm add @appsurify-testmap/google-custom-event-tracker

📚 Usage

ESM

import { initTracker } from "@appsurify-testmap/google-custom-event-tracker";

initTracker({
  send(payload) {
    gtag("event", "ui_event", payload);
  },
  debug: false, // Set to true for detailed console logging
});

CommonJS

const { initTracker } = require("@appsurify-testmap/google-custom-event-tracker");

initTracker({
  send: (payload) => gtag("event", "ui_event", payload),
});

🌐 CDN Usage (UMD)

You can include the library directly via a <script> tag.

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/@appsurify-testmap/google-custom-event-tracker/dist/google-custom-event.umd.js"></script>

unpkg

<script src="https://unpkg.com/@appsurify-testmap/google-custom-event-tracker/dist/google-custom-event.umd.js"></script>

After loading the UMD bundle the global object is available as:

window.GoogleCustomEventTracker;

🚀 Quick Start with GA4 (gtag.js)

Add the standard GA4 snippet:

<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }

  gtag("js", new Date());
  gtag("config", "G-XXXX");
</script>

Now include and initialize the tracker:

<script src="https://cdn.jsdelivr.net/npm/@appsurify-testmap/google-custom-event-tracker/dist/google-custom-event.umd.js"></script>
<script>
  window.GoogleCustomEvent.init({
    send(payload) {
      gtag("event", "ui_event", payload);
    },
  });
</script>

🏷 GTM Integration (dataLayer)

If your site uses Google Tag Manager:

<script src="https://cdn.jsdelivr.net/npm/@appsurify-testmap/google-custom-event-tracker/dist/google-custom-event.umd.js"></script>
<script>
  window.GoogleCustomEvent.init({
    send(payload) {
      window.dataLayer.push({
        event: "ui_event",
        ...payload,
      });
    },
  });
</script>

In GTM create a Custom Event Trigger with Event name: ui_event

🧪 What the Tracker Captures

On user interaction (click, input, etc.) the tracker sends:

{
  "type": "click",
  "tag": "button",
  "selector": "v1.0: body :: button[id=\"submit\",text=\"Submit\"]",
  "text": "Submit",
  "ts": 1737139231
}

The selector field uses SEQL (Semantic Element Query Language) format, which provides stable element identification that survives DOM restructuring and CSS changes.

Settings allow enabling/disabling:

initTracker({
  captureSelector: true,
  captureText: true,
  debug: false, // Enable debug logging
  seqlOptions: {}, // Options for SEQL selector generation
});

🧩 TypeScript Support

The package ships with full declaration files:

dist/google-custom-event-tracker.d.ts

TypeScript will automatically pick up the types:

import type { TrackerOptions, TrackerEvent } from "@appsurify-testmap/google-custom-event-tracker";

🔐 Browser Support

The UMD build works in:

• Chrome
• Firefox
• Safari
• Edge

ESM works in all modern browsers and bundlers.

🐛 Debug Mode

Enable debug mode to see detailed logging in the console:

initTracker({
  debug: true,
  send(payload) {
    gtag("event", "ui_event", payload);
  },
});

When debug mode is enabled, the tracker will log:

• All captured events with full payload details
• Errors during selector generation with element references
• Warnings when selector generation fails

This is useful for troubleshooting and understanding what data is being captured.

📄 License

MIT