dataLayer and GA4 events
The events Benson pushes to window.dataLayer and GA4, their fields, when they fire, and how to use them in Google Tag Manager.
Jump to a section
Benson pushes its events to window.dataLayer, so Google Tag Manager and your own analytics can see when a coupon extension turns up, when Benson hides its pop-up, and what your discount widget does. It's on for every site by default. You don't need to add any code.
Turning it on and off#
Go to Settings → Tracking → Integrations. There are two switches:
- dataLayer events (on by default) pushes each event to
window.dataLayer. Benson creates the array if your page doesn't have one. - GA4 events (off by default) sends the same events straight to Google Analytics 4 with
gtag("event", ...), ifgtagis on the page.
On Shopify, the dataLayer switch is also in the Benson app's settings. Neither switch needs a reinstall.
Use one route into GA4, not both. If GA4 events are on and a GTM tag also forwards the dataLayer events to GA4, every event is counted twice.
The events#
| Event | When it fires |
|---|---|
benson_ext_detected | Benson detects a coupon extension in the session. |
benson_agent_detected | Benson detects an AI shopping agent or automation in the session. |
benson_ext_blocked | A blocking rule matches an extension's pop-up. benson_mode says whether Benson hid it. |
benson_widget_shown | Your discount widget opens on its own for the first time (not when a shopper clicks the launcher). |
benson_code_applied | A code from your widget is applied to the cart. |
benson_state | Every page: whether this session has a coupon extension or AI agent so far, and which tools Benson has loaded. Pushed again when Benson detects a new extension or agent, or loads a tool. |
benson_ext_detected#
window.dataLayer.push({
event: "benson_ext_detected",
benson_actor_class: "extension",
benson_actor_id: "honey",
benson_confidence: 0.96,
});
| Field | Value |
|---|---|
benson_actor_class | extension, ai_agent or automation |
benson_actor_id | Which one, as a lowercase slug, such as honey, capital_one_shopping or rakuten |
benson_confidence | How sure the detection is, from 0 to 1 |
benson_agent_detected#
window.dataLayer.push({
event: "benson_agent_detected",
benson_actor_class: "ai_agent",
benson_actor_id: "chatgpt_agent",
benson_confidence: 0.9,
});
It has the same fields as benson_ext_detected. benson_actor_class is ai_agent (an agent shopping for a person, such as ChatGPT agent or Perplexity Comet) or automation (headless browsers and scripts). Use it to keep agent visits out of your conversion audiences, or to send them to a different tag. People never trigger it. See AI agents for the same signal in JavaScript and on the page.
benson_ext_blocked#
window.dataLayer.push({
event: "benson_ext_blocked",
benson_actor_class: "extension",
benson_actor_id: "honey",
benson_confidence: 0.96,
benson_mode: "block",
});
It has the same fields as benson_ext_detected, plus:
| Field | Value |
|---|---|
benson_mode | block if Benson hid the pop-up. observe if the rule only watches, or the session is in a holdout, so the shopper still saw it. |
To count pop-ups actually hidden, filter on benson_mode equals block.
benson_widget_shown#
window.dataLayer.push({
event: "benson_widget_shown",
benson_campaign: "cmp_8f2k1",
benson_trigger: "exit_intent",
});
| Field | Value |
|---|---|
benson_campaign | The campaign's id |
benson_trigger | What opened it: immediate, delay, scroll, exit_intent, mobile_exit or tab_return |
benson_code_applied#
window.dataLayer.push({
event: "benson_code_applied",
benson_campaign: "cmp_8f2k1",
benson_method: "cart_api",
});
| Field | Value |
|---|---|
benson_campaign | The campaign's id |
benson_method | How the code went on: cart_api (the store's cart), handler (your registerApplyHandler function) or promo_input (typed into the store's discount field) |
The code itself is never included.
benson_state#
window.dataLayer.push({
event: "benson_state",
benson_ext_shopper: true,
benson_extensions: "capital_one_shopping,honey",
benson_tools: "reviews_widget",
benson_agent: "",
});
| Field | Value |
|---|---|
benson_ext_shopper | true if Benson has detected a coupon extension in this session, else false |
benson_extensions | The extensions detected so far, comma-separated in alphabetical order (empty if none) |
benson_tools | The keys of the third-party tools Benson has loaded in this session, comma-separated in alphabetical order (empty if none) |
benson_agent | The AI agents and automation detected in this session, as class:id keys such as ai_agent:chatgpt_agent, comma-separated in alphabetical order (empty if none) |
GTM forgets dataLayer values on every page load, and the other events fire once per session. benson_state gives each page the session's answer, so a tag on page five still knows the shopper has Honey. On a single-page app it's pushed again on each Benson.page(). It's also pushed again when Benson loads a tool.
benson_tools says Benson loaded a tool, not that the shopper used it. Comparing sessions with and without a tool in GA4 describes who got it; a measurement says what it adds.
When events fire#
- Once per session. Each event fires once per Benson session for each extension, campaign or code. A shopper who browses ten pages with Honey installed gives you one
benson_ext_detected, not ten.benson_stateis the exception: once per page. - Every session. Events fire whether or not Benson is measuring the session for your reports (see sampling in Settings → Tracking).
- Positive detections only. Borderline matches that Benson isn't confident about never reach the dataLayer.
- After the page loads. Benson waits for the page to finish loading before it starts, so it never slows down your page. Anything it detected before then is pushed as soon as it starts.
- Consent. Under strict mode, nothing is pushed while the shopper hasn't agreed.
- No personal data. Events never carry discount codes, session ids, visitor ids or anything that identifies a shopper.
If you need every detection on the page, including low-confidence matches, subscribe with Benson.on() instead. It fires whenever Benson grows more sure of a match, without the once-per-session rule.
Using the events in Google Tag Manager#
- Add a trigger. Create a Custom Event trigger with the event name
benson_ext_detected. To catch the four session events with one trigger, use^benson_(ext|widget|code)_and tick Use regex matching. Keepbenson_stateon its own trigger: it fires on every page, so a broad^benson_trigger would send an extra event per page view. - Add variables. Create a Data Layer Variable for each field you need, such as
benson_actor_idandbenson_mode. For a value every tag on the page can read, usebenson_ext_shopperfrombenson_state, for example as a GA4 user property. - Send them on. Add a Google Analytics: GA4 Event tag on that trigger, with your variables as event parameters, for example
actor_idset to{{benson_actor_id}}. - Register the parameters in GA4 as custom dimensions so you can use them in reports and explorations.
- Publish the container.
Measure extension impact yourself shows how to use these events to compare extension sessions with everyone else.
GA4 without Tag Manager#
With GA4 events on, Benson calls gtag directly. It uses the same event names with the benson_ prefix dropped from the fields:
gtag("event", "benson_ext_detected", {
actor_class: "extension",
actor_id: "honey",
confidence: 0.96,
});
Nothing is sent if gtag isn't on the page. benson_state is a dataLayer push only and never goes to gtag.
Checking it works#
Open your store in a browser with a coupon extension installed, such as PayPal Honey, then run this in the console:
window.dataLayer.filter((e) => String(e.event).startsWith("benson_"));
GTM's Preview mode also lists each Benson event as it arrives. Because events fire once per session, open a new private window to see them again.
Test links don't push dataLayer or GA4 events, so a test never shows up in your analytics.
Stuck? Email [email protected].
