Connecting events

In some cases you might want to forward events that pagent tracks to your own tooling. For this purpose, you can setup an event listener on the pagent:event bus on the window object and receive all events that pagent is tracking or creating.

Here is an example:

<script>
  window.addEventListener('pagent:event', (e) => {
      console.log("pagent:event", e.detail);
  });
</script>

Note: If no session is active, pagent will not emit any events on the pagent:event bus.

Event data

Event types

Below is an overview of all event kinds that pagent emits together with their additional payload properties.

Event kindAdditional fieldsDescription
click
selector_css?, selector_xpath?, position_x?, position_y?
Fired whenever the visitor clicks anywhere on the page.
page_view—Fired each time a page is loaded or navigated to.
opt_in—Fired when the visitor explicitly opts-in to tracking.
opt_out—Fired when the visitor opts-out of tracking.
conversion
selector_css?, selector_xpath?, conversion_id?, conversion_origin (“programmatic”|“dom”), label, position_x?, position_y?
Fired when a conversion goal is recorded.
session_start
experiment_id?, variation_id?, is_control?, endpoint_id?, referrer?, referrer_domain?, cohort_id?, cohort_version?, device_model, browser_platform, browser_useragent, resolution_width, resolution_height, resolution_depth, window_client_width, window_client_height, client_time_zone, history_length, browser_language, browser_name, browser_version, connection_type, network_speed, dnt_status, battery_charging?, battery_level?
Fired the moment a new session begins.
session_end—Fired when the current session is terminated.
error
type (“exception”|“mutation_not_found”|“mutation_no_match”|“conversion_goal_not_found”|“mutation_multiple_matches”), error?, selector_css?, selector_xpath?, description?, original?, expected?, mutation_id?, conversion_id?
Fired whenever an error occurs while running pagent.
highlight_text
selector_css?, selector_xpath?, label, position_x?, position_y?
Fired when pagent highlights text on the page.
element_view
mutation_id?, conversion_id?, selector_css, selector_xpath, position_x?, position_y?
Fired when a tracked element scrolls into the viewport.
hoverposition_x?, position_y?Fired when the visitor hovers over a tracked element.
session_ping—Sent periodically while a session is active to keep it alive.

(Fields marked with ? are optional.)

Common properties

The following attributes are included in every event:

PropertyTypeDescription
session_idstringUnique identifier of the current session.
visit_idstringUnique identifier of the current page view.
timenumberUnix timestamp in milliseconds when the event occurred.
is_uniqueboolean (optional)true if this is the first time this event type was emitted during the session.
is_opted_inbooleanIndicates whether the visitor has opted-in to tracking.
session_durationnumberSession duration in milliseconds at the moment the event was emitted.
scroll_depthnumberMaximum vertical scroll position in pixels that the visitor has reached so far.
scroll_percentagenumberPercentage of the page that has been scrolled.
urlstringAbsolute URL of the page where the event happened.

Example integration

You can also forward individual pagent events to other analytics platforms. The following example shows how to send the conversion event to JENTIS using its push-based data layer:

<script>
  // Keep track of the current session
  let session = null;

  // Forward pagent "conversion" events to the JENTIS data layer
  window.addEventListener('pagent:event', (e) => {
    const event = e.detail;

    // Store the session start event in case we are running an experiment
    if (event.kind === 'session_start' && event.experiment_id) {
      session = event;
      return;
    }

    // Only track conversions for active experiments
    if (!session || event.kind !== "conversion") return;

    // Prepare the JENTIS queue (it as a simple array on window)
    window._jts = window._jts || [];

    // Push the event object itself
    _jts.push({
      track: 'event', // JENTIS track command
      group: 'generic', // optional grouping
      context: 'pagent', // helps to identify the source
      kind: 'conversion', // helps to identify the event type
      experiment_id: session.experiment_id, // unique identifier of the experiment
      variation_id: session.variation_id, // unique identifier of the variation
      cohort_id: session.cohort_id, // unique identifier of the cohort
      is_control: session.is_control // whether the displayed variation is control
    });

    // Finally submit everything to JENTIS
    _jts.push({ track: 'submit' });
  });
</script>

This keeps your implementation lightweight. You only need to listen for pagent events and decide which ones you want to forward. The example above listens exclusively for the conversion event and immediately submits it to JENTIS.