HeadQ supports custom event listeners, allowing you to hook into key user interactions and extend storefront behavior programmatically.
This feature is designed for developers who want to react to user actions such as adding items to the cart, starting checkout, or completing a purchase.
How It Works
You can now listen to HeadQ events directly by using the global headq.on function. This method allows you to subscribe to specific events and handle them as needed in your frontend JavaScript.
Basic Syntax
headq.on('<event_name>', (data) => {
// Your custom logic here
});Supported Events
Below is a complete list of available events and when they are triggered:
| Event Name | Description |
|---|---|
view_item |
The user opens a product configurator |
add_to_cart |
The user adds a product to the cart |
add_to_quote_cart |
The user adds a product to the quote cart |
view_cart |
The user opens the cart |
begin_checkout |
The user starts the checkout process |
purchase |
The user finalizes the checkout process and makes a purchase |
request_for_quote |
The user requests a quote |
calculate_price |
The price was calculated in the configurator |
begin_configuration |
The user started the configuration but did not calculate the price |
complete_configuration |
The user has completed the configuration and added it to the cart |
generate_lead |
The user has done an action that generates a lead to the store |
remove_from_cart |
The user has removed the item from the cart |
remove_from_quote_cart |
The user has removed the item from the quote cart |
Example Event Usage
add_to_cart
Triggered when a user adds a product to the cart.
headq.on('add_to_cart', (data) => {
console.log('Product added to cart:', data);
});begin_checkout
Triggered when a user starts the checkout process.
headq.on('begin_checkout', (data) => {
console.log('Checkout started:', data);
});purchase
Triggered when a purchase is completed successfully.
headq.on('purchase', (data) => {
console.log('Purchase completed:', data);
});Best Practices
-
Make sure your code does not block the main thread. Use asynchronous functions if needed.
-
Always check for the presence of expected fields in the
dataobject. -
Avoid placing sensitive or business-critical logic solely inside event listeners.
FAQ
Q: Do I need to enable this feature separately?
No, event listeners are available by default when the storefront is running HeadQ.
Q: Can I remove an event listener?
Currently, event removal is not supported. However, you can use flags within your callback logic if you need to conditionally ignore events.