Here are the steps you need to take to track custom events such as purchases, signups, button clicks or form submissions.
1. Change the vince snippet on your site
Please change the file name in the src attribute of your vince snippet from script.js to script.tagged-events.js. It should look like this:
<script defer data-domain="yourdomain.com" src="http://localhost:8080/js/script.tagged-events.js"></script>
If you’re using outbound link clicks, file downloads or any of our other script extensions, you can combine them by changing the
srcattribute in the snippet. If you want to track custom events and outbound link clicks simultaneously, change the script name toscript.tagged-events.outbound-links.js.
2. Add a CSS class name to the element you want to track on your site
Tag the site element you want to track with a CSS class name. How to do this varies depending on the site builder, CMS or framework you’ve used to build your site.
For instance, if you’re using WordPress, you can click on any block element you want to track such as a button or a form. This will open up the block menu on the right-hand side of your screen.
You can then click on “Advanced” and add a CSS class name in the “Additional CSS class(es)” field. Add the CSS class name in this format: vince-event-name=MyEventName. For instance, if you want to track form submissions on your contact form, you could use: vince-event-name=Form+Submit.
When tracking form submits, it is important to tag the <form> element itself with the vince-event-name=... class (not the input or button element inside the form). Normally, vince can track button clicks, but if a button is inside a form, it will navigate to the next page often leaving not enough time for the event to finish.
To represent a space character in the event names, you can use a
+sign. For example:vince-event-name=Form+Submitwill display asForm Submitin your dashboardSome CMSs (like Webflow) do not support an equals sign (
=) in the classnames. If that’s the case, use a double dash (--) instead of the equals sign. For example:vince-event-name--signup.
You can also add class names directly in HTML
If you can edit the raw HTML code of the element you want to track, you can also add the classes directly in HTML. For example:
<!-- before -->
<button>Click Me</button>
<!-- after -->
<button class="vince-event-name=Button+Click">Click Me</button>
Or if your element already has a class attribute, just separate the new ones with a space:
<!-- before -->
<button class="some-existing-class">Click Me</button>
<!-- after -->
<button class="some-existing-class vince-event-name=Button+Click">Click Me</button>
Verify that the CSS classes were added correctly
After adding the class, please go back to your site, and verify that the class attribute got added with the exact required format. You can check it by right-clicking the element and inspecting it. This will show you the HTML code of the element.
In some cases, the tracking classes might be added to a wrapper <div> element (parent to the element you want to track), but don’t worry, vince will still be able to track clicks on the child element if its parent has the necessary classes.
Some CMSs like Webflow do not support an equals sign (=) in the classnames. If you add a class attribute with the value vince-event-name=Signup, but when you go back to your page and inspect the element, it might have class="vince-event-name-Signup" (equals sign replaced with a hyphen).
If that’s the case, use a double dash (--) instead of the equals sign. For example: vince-event-name--signup.
Tracking form submissions may currently not work with forms that contain an element with
id="submit"orname="submit". To work around this limitation please rename theidornameattribute value to something else. If you’re unable to do that, please look into implementing custom events manually with JavaScript
If your CMS does not support adding CSS classes, please expand the following section of instructions.
My site builder does not support adding CSS classes
If you’re unable to add the classnames in your page editor, there’s still a way for you to track custom events. This method includes copying and pasting some JavaScript code onto your page.
This approach will be using the id attribute of your element, to add the CSS classes dynamically with JavaScript. The id attribute should already be present on your element in most site builders.
1. Verify that your element has an `id` attribute
Go to your website, right-click and inspect the element you want to track, which will show you the HTML code of that element. If there is the id="...." attribute, no matter the value, you can proceed to step 3.
2. Add an `id` attribute in your CMS
If the element you want to track does not have an id attribute by default, you can try adding one in the edit mode of your CMS. However, if you don’t have that option, then this approach will be impossible and you will have to check out the section at the bottom of this page - implementing custom events manually with JavaScript.
3. Add the JavaScript code to your page
Once you have the id attribute, you can use it to add the CSS classnames dynamically with JavaScript. Here’s the code that does that:
<script>
var toTag = [
{
elementId: 'my-element-id',
classes: 'vince-event-name=<event_name>'
}
]
document.addEventListener('DOMContentLoaded', function (_e) {
toTag.forEach(function (tagObject) {
var element = document.getElementById(tagObject.elementId)
tagObject.classes.split(' ').forEach(function (className) {
if (element) { element.classList.add(className) }
})
})
})
</script>
You should copy this code into the <head> section of your page, and make the following adjustments to it:
- In the line that says
elementId: 'my-element-id, replacemy-element-idwith theidvalue from step 2 or 3. - In the line that says
classes: 'vince-event-name=Event+Name', replaceEvent+Namewith your desired custom event name. This will be the goal name that will be displayed in your dashboard later.
Once you have this script inserted on your page, vince will be able to track your element.
4. Want to track multiple elements?
If you want to track multiple elements accross your site, you can use the same code from step 3 on all of your pages. The only modification you will have to make, is list as many pairs of elementId and classes as you want. For example, if you want to track three elements:
var toTag = [
{
elementId: 'id-1',
classes: 'vince-event-name=My+First+Goal'
},
{
elementId: 'id-2',
classes: 'vince-event-name=My+Second+Goal'
},
{
elementId: 'id-3',
classes: 'vince-event-name=My+Third+Goal'
},
]
3. Create a custom event goal in your vince instance
When you send custom events to vince, they won’t show up in your dashboard automatically. You’ll have to configure the goal for the conversion numbers to show up.
To configure a goal, go to your website’s settings in your vince account and visit the “Goals” section. You should see an empty list with a prompt to add a goal.
Click on the “+ Add goal” button to go to the goal creation form.
Select Custom event as the goal trigger and enter the name of the custom event you are triggering. The name must match the one you added as a CSS class name on your site for conversions to appear in your analytics dashboard. So in our example where you added a CSS class name vince-event-name=Form+Submit, the goal to add to your vince account is Form Submit (plus is replaced by a space).
Next, click on the “Add goal” button and you’ll be taken back to the Goals page. When you navigate back to your vince dashboard, you should see the number of visitors who triggered the custom event. Custom events are listed at the bottom of your dashboard and will appear as soon as the first conversion has been tracked.
That’s it. You’re now tracking goal conversions.
Trigger custom events manually with a JavaScript function
For more specific tracking needs, you will have to write the JavaScript yourself. The API only consists of one function, which you can use in your code by including the second line in your tracking setup, as shown below:
<script defer data-domain="yourdomain.com" src="http://localhost:8080/js/script.js"></script>
<script>window.vince = window.vince || function() { (window.vince.q = window.vince.q || []).push(arguments) }</script>
This snippet creates a global function called vince which can be used to trigger custom events from anywhere in your code.
Here’s what triggering a custom event looks like:
vince('Signup')
The first argument to this function (“Signup” in this case) is the name of your custom event (i.e. the name of your goal).
Example: Tracking audio and video elements
- Give your audio or video element an
idattribute to use it with JavaScript. If it already has anid, feel free to use that instead oftrackedMediain this example.
<audio id="trackedMedia" controls src="your_audio.mp3">
Your browser doesn't support this audio element
</audio>
- Add the below script to your HTML page with the media element. In order to be able to use the media element with JavaScript, the script should be inserted after the media element itself. It is safe to insert it at the end of the
<body>section, just before the closing</body>tag.
<script>
var mediaElement = document.getElementById('trackedMedia')
// Set a flag to ignore the case where playing has already started and is resumed from paused state
var mediaAlreadyStarted = false
// Listen to the 'play' event on the media element. Ignore if already started playing and not finished yet
mediaElement.addEventListener('play', function (e) {
if (!mediaAlreadyStarted) {
mediaAlreadyStarted = true
vince('Media Played')
}
})
// Listen to the 'ended' event on the media element to reset the flag and start listening again
mediaElement.addEventListener('ended', function (e) {
mediaAlreadyStarted = false
})
</script>
The same code also applies for <video> elements. Feel free to replace Media Played with a more suitable name for your custom event.