📦 Installation

NPM

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

Yarn

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

PNPM

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

---

📚 Usage

ESM

`ts
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

`js
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
`

unpkg

`html

`

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

`js
window.GoogleCustomEventTracker;
`

---

🚀 Quick Start with GA4 (gtag.js)

Add the standard GA4 snippet:

`html


`

Now include and initialize the tracker:

`html


`

---

🏷 GTM Integration (dataLayer)

If your site uses Google Tag Manager:

`html


`

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:

`json
{
"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:

`ts
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:

`ts
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:

`ts
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