Events represent actions that a user took while on your site. These events are defined and passed to Contentsquare through your client-side code via the Events API.
With JavaScript, you're able to set up your own criteria to determine what kind of action results in an event being sent to us. The event could be sent as soon as the page loads, when a modal appears, or when a user sees a specific variation of your page through an A/B test.
The Events API call
Below is the basic format for a call to the Events API:
window._uxa.push(["event", "eventName"]);
- The first parameter should always contain the string value event.
- The second parameter is the custom name assigned to your event. In the example above, the event name is action_name, but this can be anything you choose. (Example: 'opened_modal', 'shown_variant_a', etc.)
Below is an example of sending an event that you can use to trigger a survey when a user clicks on a Subscribe button.
window._uxa.push(["event", "subscribed_to_email_list"]);
Be aware of the limitations when implementing events
-
Naming your Events
The event name must not exceed 250 characters and can only contain any of the following: alphanumeric characters (a-z, A-Z, 0-9), spaces, underscores (_), dashes (-), periods (.), colons (:) and forward slashes (/).
-
There is a 10,000 unique event limit per site
We support 10,000 unique events per site, with an unlimited number of users associated with those events. If you exceed this, only 10,000 of the most used events (sorted 0-9, a-Z) will be available.
-
It's not currently possible to pass any event properties with the event.
Best practices
-
Do not pass Personal Identifying Information as an Event
Personal identifying information (PII) should never be used as events. If you'd like to connect data with specific users, you should explore the User Attributes feature instead.
-
If you're also making Identify API calls, these need to be executed before Event API calls
You might want to combine Events with User Attribute-based targeting for triggering a survey. To set this up, the order of execution requires the Identify API call to happen before the Event API call, keeping in mind any asynchronous calls to other services. If the Event API call is executed before the Identify API call has finished execution, the survey won't show.
-
Events cannot be used to collect email or IP addresses, or numbers with 9 or more digits
Since there is currently no way to use our User Lookup tool with events, they cannot be used to collect emails, IP addresses, or numbers with 9 or more digits to prevent credit card numbers from being passed to Contentsquare. This decision has been based on the General Data Protection Regulation (GDPR). If you'd like to collect email addresses with your user's consent and in line with GDPR, you can do so with User Attributes.
-
For e-commerce sites, avoid sending specific product information
This includes information such as SKU codes. Usually, URLs are more useful and are captured by default.
-
Be careful when sending values from objects such as GTM data layers
These often hold more data than you expect.
- Avoid passing anything like dates or timestamps
- Avoid passing anything from URLs such as referral codes
- Avoid passing detailed errors logs
Testing Events
Following the steps below will allow you to confirm if your Events API calls are successfully received by Contentsquare. If you're not familiar with your browser console or developer tools, consider looping in a team member who has more knowledge of these tools or a web developer to assist you.
1. Enable debug logs in your browser console.
Open the page where you want to test the Event and add the ?hjDebug=1 parameter to the end of the URL. Here are a couple of examples of what it might look like:
https://www.example.com/?hjDebug=1
OR
https://www.example.com/?utm_1234&hjDebug=1
2. Open your browser console.
If you're not familiar with your browser developer tools, or the console, check out this guide to learn how to open your browser console.
3. Fire the event manually.
To fire your event manually, add the Event API code in your browser console and press Enter or Return on your keyboard. If the event fired successfully, you'll see a confirmation log similar to:
COMMAND: Processing command: event example_action
We also recommend that you go through the steps that your user would, to trigger the event automatically. If the event is fired automatically, then you'll know that your code is implemented successfully.
If the same event is detected when fired manually, but not automatically when testing the user journey, then you may need to revisit your code and criteria that determine when the Event API call is sent.