Instrumentation

Many sites already announce what visitors do: a Google Tag Manager dataLayer.push on purchase, a CustomEvent when a form is sent, a gtag event call. pagent can listen for these and record them as events, so you don’t have to add window._pgnt.push calls to your code. There are three ways to instrument a site from pagent: All three produce ordinary events. Build conversion goals on them the same way as on events your code reports.

​

Observed events

An observed event is a definition that tells the SDK: “when the page pushes purchase into dataLayer, record a pagent event called purchase”. The SDK only listens for events you defined. It does not collect anything else from your dataLayer.

​

Record and define events with the Chrome extension

The fastest way to find what your site emits is the Events recorder in the pagent Chrome extension. The SDK picks up new definitions within about a minute. The events then appear under Tracking → Sources → Events with the source dataLayer or Window event and the status Defined.

​

What the SDK listens for

• dataLayer pushes in both common shapes: GTM objects with an event key, and gtag calls such as gtag("event", "purchase", { value: 49.99 }).
  window.dataLayer.push({ event: "purchase", ecommerce: { value: 49.99, currency: "EUR" } });
  
  Entries pushed before the SDK loaded are replayed, so early pushes are not lost. Your dataLayer keeps working exactly as before: the page’s own push runs first and pagent never throws into it.
• Window events: a CustomEvent dispatched anywhere on the page. Properties and revenue are read from the event’s detail.
  window.dispatchEvent(new CustomEvent("newsletter:subscribed", { detail: { list: "weekly" } }));
  

Only the declared properties and the revenue field leave the page. The rest of the payload is never sent to pagent.

​

Editing a definition

Open Tracking → Sources → Events and choose Edit definition on the event. You can change the display name, description, page scope, forwarded properties and revenue path. The label cannot change: it links everything already recorded. A page scope only limits where the SDK listens. It never filters events that were already recorded.

​

Observed vs defined

Events you report with window._pgnt.push or the REST API register themselves on first use. Their status is Observed until you edit their definition, after which it is Defined. Both statuses work the same for goals. Observed dataLayer and window events only have history from the moment their definition was published. Reported events have history from the first time your code sent them.

​

Triggers as events

A trigger (under Triggers in pagent) already describes a condition on your site, for example “cart has items” or “visitor came from a paid campaign”. You can record every page view where it matches as an event.

1. Open Tracking → Sources → Events and click Track a trigger.
2. Pick the Trigger, enter a Label such as cart_has_items, and optionally a display name.
3. Click Add event.

The event is recorded on every page view where the trigger matches. Create an event goal on it to measure it in tests.

​

Instrumentation scripts

When an action cannot be observed from a dataLayer push or a window event, an instrumentation script can detect it and report it. Scripts are short snippets the SDK runs once per page load.

1. Open Tracking → Instrumentation and click New script.
2. Give it a Name, for example Newsletter signup bridge.
3. Write the Code. Report events with window._pgnt.push:
   document.addEventListener("submit", (e) => {
       if (e.target.matches("#newsletter")) {
           window._pgnt.push({ kind: "event", label: "newsletter_signup" });
       }
   }, true);
   
4. Leave Run at page start on to run it on every page, or turn it off and pick a Trigger to run it only where that trigger matches.
5. Make sure the script is Enabled and save.

Keep scripts safe to run more than once, and report events rather than conversions.