Once your configurator is built, you may want to learn how it's being used by actual customers. Not just what configurations and quotes are being built, but how they are being built. For example, you may want to learn:
- how much time do your users spend in a configuator overall? Or on each page within the configurator?
- how often do they abandon a configuration? Where were they when it was abandoned?
- how often is a certain field changed before they decide on an option?
With Epicor CPQ, you can use the same powerful tools which web designers already use worldwide to measure and improve their web pages.
You can track user actions in your configurator, and send those actions to a digital analytics platform, such as Google Analytics, Matomo, Mixpanel, Adobe Analytics, or any other service.
General overview
1. As you know, any ordinary web page can serve content.
2. By placing some analytics javascript into that web page,
3. You enable your analytics platform to track when users open and view that web page.
4. You can also track specific user events on that web page, such as clicking buttons or making a selection.
5. Separately, a Epicor CPQ configurator can be embedded into your web page.
6. An Epicor CPQ message rule can pass data from the embedded configurator to the enclosing web page. Once there, it's a trackable event to your analytics platform.
7. In this way, you are in complete control of what events you want to track, and which analytics platform you would like to use.
To summarize, your configurator will not connect directly to your analytics platform. Rather, your configurator simply sends messages to the enclosing web page, which serves as a middleman to relay that information to the analytics platform. In addition, you can clearly separate (and troubleshoot) the two steps: gathering events from your configurator, and sending events to the analytics platform.
Technical prerequisites
The rest of this blog entry goes over the technical specifics of connecting your digital analytics platform to a Epicor CPQ configurator or stand-alone scene.
You might want to review the Embed API and Message Rules topics first, before learning about this topic.
You should also have an existing account at a digital analytics platform ready for use.
Set up and confirm your analytics platform
Before you start gathering usage data from your configurator on an analytics platform, you should have that platform set up correctly first. To confirm, create a simple "hello world" HTML web page with three buttons inside it to test your analytics setup. This test web page should accomplish two tasks:
When the web page is loaded, a "page visited" event should appear in your analytics package.
And each time you click one of the buttons within that page, a "button X clicked" event should also appear separately in your analytics package.
For specific instructions on setting up a basic "hello world" test of your analytics platform, consult the instructions that came with your package, or work with your web analytics team. For demonstration purposes, we'll be using Google Tag Manager, but remember that any analytics platform which allows you to send events through javascript is supported.
Here's the HTML for a basic web page, with no analytics:
<html> <head> </head> <body>
<h3>This is the enclosing web page.</h3> <button type="button" onclick="alert('Button 1 clicked!')">Button One</button> <button type="button" onclick="alert('Button 2 clicked!')">Button Two</button> <button type="button" onclick="alert('Button 3 clicked!')">Button Three</button> </body>
</html>Here is that same web page, but with the necessary connections to one of many analytics platforms (in this example, Google Tag Manager, but any platform can be used). This example accomplishes the two tasks above: first, the analytics platform logs a pageCategory and visitorType when the page is loaded. Second, it logs a specific event button[x]-click when each of the 3 buttons are pressed.
<html><head> <!-- Google Tag Manager --> <script> dataLayer = [{
'pageCategory': 'configure',
'visitorType': 'high-value'
}];
</script> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXX');</script> <!-- End Google Tag Manager --></head><body> <h3>This is the enclosing web page.</h3> <button type="button" onclick="alert('Button 1 clicked!'); dataLayer.push({'event': 'button1-click'});">Button One</button> <button type="button" onclick="alert('Button 2 clicked!'); dataLayer.push({'event': 'button2-click'});">Button Two</button> <button type="button" onclick="alert('Button 3 clicked!'); dataLayer.push({'event': 'button3-click'});">Button Three</button></body></html>Be sure you can create a similar simple web page – and can see your analytics data appearing – before proceeding with the rest of this walkthrough. Depending on your analytics platform, the javascript you add will be different. Copy-pasting the example code above won't work: you'll need to edit it first.
This is a great time to work closely with your company's webmaster or marketing team. Chances are, they already use an analytics platform and are familiar with how to insert the necessary javascript into the example page above. They can also insert any required brand elements or other features to ensure the web page matches your corporate style guidelines, and host the web page in the proper location.
Insert your configurator into the web page
Now that we have a web page with working analytics, let's add our configurator. For specifics on the various options available, please see the Embed API page. Epicor CPQ offers two techniques to embed your configurator: by using HTML or by using JavaScript. Here, we use JavaScript.
<html><head> <!-- Google Tag Manager --> <script> dataLayer = [{
'pageCategory': 'configure',
'visitorType': 'high-value'
}];
</script> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXX');</script> <!-- End Google Tag Manager --></head><body><!-- Epicor CPQ configurator javascript starts --><script src="https://yourCompanyName-dev.kbmax.com/embed.min.js"></script><script> //set up the configurator itself
document.addEventListener("DOMContentLoaded", function() {
//start the embed
var config = new kbmax.ConfiguratorEmbed({
elementId: "viewer",
configuratorId: 87,
showFields: true,
showHeader: false,
showConfigHeader: false,
showDrawer: true,
showMove: false,
bindToFormSelector: "",
loadStyle: "progress",
progressColor: "orange" });
});
</script><!-- Epicor CPQ configurator javascript ends --> <h3>This is the enclosing web page.</h3> <button type="button" onclick="alert('Button 1 clicked!'); dataLayer.push({'event': 'button1-click'});">Button One</button> <button type="button" onclick="alert('Button 2 clicked!'); dataLayer.push({'event': 'button2-click'});">Button Two</button> <button type="button" onclick="alert('Button 3 clicked!'); dataLayer.push({'event': 'button3-click'});">Button Three</button> <!-- Epicor CPQ configurator embed starts --> <h3>This is the embedded configurator.</h3> <div id="viewer" style="height: 800px;"></div> <!-- Epicor CPQ configurator embed ends--></body></html>Run this updated web page, and you'll see the configurator appear within the page.
Add message rules to your configurator, to send data to the web page
Let's step away from the web page for a moment, and focus back on the configurator. If we want to track certain events in the configurator's life between when it was loaded and when it was finally submitted (or abandoned), we must create Snap rules that will be triggered by that event, and send a message with the appropriate data inside.
For this example, we want to simply track when the user moved from one configurator page to the next. So we will create a new Page Changed rule in our configurator:
Now, whenever the user visits a page in the configurator, it will send a message to the enclosing web page. Don't worry: messages sent by your configurator fail gracefully. If there is no enclosing web page, or if that web page isn't receiving messages, nothing happens.
Add JavaScript to the web page, to catch the data from your configurator
Let's first confirm that our message is being sent to the enclosing web page. Once we can see the message arrive on the web page from the embedded configurator, then we can send it to the analytics platform. For testing purposes, let's add a simple DIV to our enclosing web page, and some javascript that will update that DIV with the contents of any message that comes along from the configurator:
<html><head> <!-- Google Tag Manager --> <script> dataLayer = [{
'pageCategory': 'configure',
'visitorType': 'high-value'
}];
</script> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXX');</script> <!-- End Google Tag Manager --></head><body><!-- Epicor CPQ configurator javascript starts --><script src="https://yourCompanyName-dev.kbmax.com/embed.min.js"></script><script> //set up the configurator itself
document.addEventListener("DOMContentLoaded", function() {
//start the embed
var config = new kbmax.ConfiguratorEmbed({
elementId: "viewer",
configuratorId: 87,
showFields: true,
showHeader: false,
showConfigHeader: false,
showDrawer: true,
showMove: false,
bindToFormSelector: "",
loadStyle: "progress",
progressColor: "orange" });
//given that configurator, add a handler for any inbound messages
config.onMessage.add(function (msg) {
//for testing purposes, write every message to the screen
document.getElementById("theResult").innerHTML = msg.data;
});
});
</script><!-- Epicor CPQ configurator javascript ends--> <h3>This is the enclosing web page.</h3> <button type="button" onclick="alert('Button 1 clicked!'); dataLayer.push({'event': 'button1-click'});">Button One</button> <button type="button" onclick="alert('Button 2 clicked!'); dataLayer.push({'event': 'button2-click'});">Button Two</button> <button type="button" onclick="alert('Button 3 clicked!'); dataLayer.push({'event': 'button3-click'});">Button Three</button><p>Messages value from configurator will appear below.</p><div id="theResult">(no message yet)</div> <!-- Epicor CPQ configurator embed starts --> <h3>This is the embedded configurator.</h3> <div id="viewer" style="height: 800px;"></div> <!-- Epicor CPQ configurator embed ends--></body></html>Now, when the configurator is loaded or when you move from one page to another in the embedded configurator, you'll see the text of your message appear in the DIV of the enclosing web page. Neat!
Add JavaScript to the web page, to send the data to your analytics platform
Now that we've confirmed the message is being sent from our configurator to the enclosing web page, it's a simple adjustment to have that message sent along to the analytics platform. Each platform is different, so your JavaScript may be different:
<html><head> <!-- Google Tag Manager --> <script> dataLayer = [{
'pageCategory': 'configure',
'visitorType': 'high-value'
}];
</script> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXX');</script> <!-- End Google Tag Manager --></head><body><!-- Epicor CPQ configurator javascript starts --><script src="https://yourCompanyName-dev.kbmax.com/embed.min.js"></script><script> //set up the configurator itself
document.addEventListener("DOMContentLoaded", function() {
//start the embed
var config = new kbmax.ConfiguratorEmbed({
elementId: "viewer",
configuratorId: 87,
showFields: true,
showHeader: false,
showConfigHeader: false,
showDrawer: true,
showMove: false,
bindToFormSelector: "",
loadStyle: "progress",
progressColor: "orange" });
//given that configurator, add a handler for any inbound messages
config.onMessage.add(function (msg) {
//for testing purposes, write every message to the screen
document.getElementById("theResult").innerHTML = msg.data;
//if page changed, send data to analytics
if (msg.name == "PageChangedTo") {
//start of analytics code
dataLayer.push({
"event":"EpicorCPQ",
"EpicorCPQ":msg.data,
"EpicorCPQ":"pageChange" });
//end of analytics code
}
});
});
</script><!-- Epicor CPQ configurator javascript ends--> <h3>This is the enclosing web page.</h3> <button type="button" onclick="alert('Button 1 clicked!'); dataLayer.push({'event': 'button1-click'});">Button One</button> <button type="button" onclick="alert('Button 2 clicked!'); dataLayer.push({'event': 'button2-click'});">Button Two</button> <button type="button" onclick="alert('Button 3 clicked!'); dataLayer.push({'event': 'button3-click'});">Button Three</button><p>Messages value from configurator will appear below.</p><div id="theResult">(no message yet)</div> <!-- Epicor CPQ configurator embed starts --> <h3>This is the embedded configurator.</h3> <div id="viewer" style="height: 800px;"></div> <!-- Epicor CPQ configurator embed ends--></body></html>Tips and best practices
- You're adding two separate things, so do them separately. First, add your analytics code to a simple web page, and ensure you can capture not only the page load, but also any javascript events (like simple button clicks). Only when this is working should you proceed to the next step: embedding your configurator.
- Work closely with your digital marketing team to ensure the analytics you're capturing have the correct names and attributes. When done correctly, statistics that come from Epicor CPQ can be integrated smoothly in any existing statistics you're already gathering.
- Keep in mind your 3 different Epicor CPQ environments: dev, test, and production. You'll need to specify the right environment in the embed code above, and ensure as you deploy your HTML, you adjust that environment string accordingly.