Lightweight DOM interaction tracker for GA4/gtag (click, input, keypress) with Vite bundling.
npm install @appsurify-testmap/google-custom-event-tracker``bash`
npm install @appsurify-testmap/google-custom-event-tracker
`bash`
yarn add @appsurify-testmap/google-custom-event-tracker
`bash`
pnpm add @appsurify-testmap/google-custom-event-tracker
---
`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
});
`
`js
const { initTracker } = require("@appsurify-testmap/google-custom-event-tracker");
initTracker({
send: (payload) => gtag("event", "ui_event", payload),
});
`
---
You can include the library directly via a
`
`html`
After loading the UMD bundle the global object is available as:
`js`
window.GoogleCustomEventTracker;
---
Add the standard GA4 snippet:
`html`
Now include and initialize the tracker:
`html`
---
If your site uses Google Tag Manager:
`html`
In GTM create a Custom Event Trigger with Event name: ui_event
---
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
});
---
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";
---
The UMD build works in:
- Chrome
- Firefox
- Safari
- Edge
ESM works in all modern browsers and bundlers.
---
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.
---
MIT