Userpilot Event Listener
How to track Website Visitor's Interaction With UserPilot Feedback Widget and Onboarding Flow with google tag manager
This guide will show you how to use the Userpilot event listener script and Google Tag Manager (GTM) to track website visitors’ interactions with the Userpilot feedback widget and in-app onboarding flows. By implementing this setup, you can capture detailed interaction data in analytics tools such as Google Analytics (GA4), Piwik Pro, and others.
Step 1: Add the Userpilot Event Listener Script in GTM
The first step is to copy the provided Userpilot event listener script and add it to a new custom HTML tag in Google Tag Manager.
- Log in to your GTM workspace and create a new tag.
- Select Custom HTML as the tag type.
- Paste the Userpilot event listener script into the HTML field.
- Name your tag (e.g., “Userpilot Event Listener”).
- Use the DOM Ready trigger type to ensure the script fires after the page’s DOM has fully loaded.
💡 Pro Tip: Firing on DOM Ready ensures the Userpilot widget is initialized before the event listener activates.
What Does the Event Listener Script Do?
This script listens for various Userpilot events, such as onboarding steps, feedback widget actions, and dismissals. When an interaction occurs, it triggers a dataLayer event named “userpilot_events“ with the following visitor interaction details:
- userpilot_action: Type of interaction or event (e.g., “started,” “completed,“ “dismissed,“ or “step”).
- userpilot_event_id: A unique ID for the event.
- userpilot_event_token: A token for the event.
- userpilot_step and userpilot_total_steps: (For “step“ events) The current step and the total number of steps.
Step 2: Create a Custom Event Trigger
To track these interactions, create a custom event trigger in GTM:
- Navigate to Triggers in your GTM workspace.
- Click New and select Custom Event as the trigger type.
- Name your trigger (e.g., “Userpilot Event Trigger”).
- Set the Event Name to “userpilot_events”.
- Save your trigger.
This trigger will activate for all userpilot_events captured by the event listener.
Step 3: Define Data Layer Variables
Next, create the necessary variables in GTM to capture and utilize data from the dataLayer:
- Navigate to Variables in your GTM workspace.
- Create a Data Layer Variable for each key in the event data:
- userpilot_action: Indicates the type of Userpilot interaction/event.
- userpilot_event_id: Provides the unique ID of the Userpilot event.
- userpilot_event_token: Contains the event token for tracking.
- userpilot_step: (Optional) Tracks the current onboarding step.
- userpilot_total_steps: (Optional) Tracks the total steps in the onboarding flow.
- Save each variable for use in your tag configurations.
Step 4: Create Marketing Tags and Pixels
After creating triggers and variables, set up your marketing tags or pixels to utilize this data.
- Create new tags for platforms like Google Analytics (GA4), Piwik Pro, or Facebook Pixel.
- Attach the Userpilot Event Trigger created in Step 2.
- Use the Data Layer Variables to add context to the events tracked. For example:
- Set Event Name to userpilot_action in your GA4 event configuration.
- Include additional information like userpilot_step and userpilot_total_steps in the event parameters.
This allows you to monitor onboarding flow and feedback widget interactions in your analytics tools, enhancing your insights.
Notes:
The Userpilot event listener is usable with any Tag Management Solution (TMS). However, the implementation principles remain consistent across platforms.
To simplify your setup process, scroll down this page to download a customizable GTM recipe template for tracking the Userpilot feedback widget and onboarding flow interactions.
Following these steps will give you a robust setup for tracking and analyzing Userpilot interactions on your website.
<script>
// Initialize dataLayer if not already present
window.dataLayer = window.dataLayer || [];
// Helper function to push event data to dataLayer
function pushToDataLayer(eventName, eventDetails) {
var eventData = {
event: "userpilot_events",
userpilot_action: eventName,
userpilot_event_id: eventDetails.id || null,
userpilot_event_token: eventDetails.token || null
};
// Add step-related data for 'step' events
if (eventName === "step") {
eventData.userpilot_step = eventDetails.step || null;
eventData.userpilot_total_steps = eventDetails.totalSteps || null;
}
// Push data to the GTM dataLayer
window.dataLayer.push(eventData);
}
// Subscribe to Userpilot events
if (window.userpilot && typeof window.userpilot.on === "function") {
// Listen for 'started' event
userpilot.on("started", function (eventDetails) {
pushToDataLayer("started", eventDetails);
});
// Listen for 'completed' event
userpilot.on("completed", function (eventDetails) {
pushToDataLayer("completed", eventDetails);
});
// Listen for 'dismissed' event
userpilot.on("dismissed", function (eventDetails) {
pushToDataLayer("dismissed", eventDetails);
});
// Listen for 'step' event
userpilot.on("step", function (eventDetails) {
pushToDataLayer("step", eventDetails);
});
} else {
console.error("Userpilot is not initialized or 'on' method is unavailable.");
}
</script>
Video of how to use the listener
Related Event Listener
UserLane
Saber Feedback
Omnisend
download the google tag manager recipe for tracking Website Visitor's Interaction With UserPilot Feedback Widget and Onboarding Flow
