Octane AI's custom events allow developers to create custom functions attached to certain quiz-related actions. Understanding how to take advantage of these custom events through the addEventListener() method will unlock a huge amount of customizability.
This MDN web document is an excellent source for an in-depth explanation of the addEventListener() method.
💡 What you'll learn about
How developer tools work (jump to section)
Octane AI's custom events (jump to section)
Listening to events with addEventListener() (jump to section)
Frequently asked questions (jump to section)
💡 Prerequisites
Developer tools are available on the Octane Plus plan.
Using these features will require you to create custom code on your website that targets with your desired developer tool. This document serves as a starting point for those with the technical proficiency to build the next steps.
How developer tools work
Octane AI offers two types of developer options:
Custom events
Disabling Octane AI behaviors
Custom events trigger automatically upon certain quiz actions. The addEventListener() method can be used to call functions when a certain event appears.
Disabling Octane AI behaviors are options available inside of the quiz editor that can be selected to replace Octane AI code with your own custom code. These options are separate from custom events.
This article will focus on Octane AI's custom events.
Octane AI's custom events
Octane AI's custom events currently include:
octane.quiz.completedoctane.quiz.accessedoctane.quiz.addToCartoctane.quiz.addToCartError
Here's a summary of each custom event. The potential use cases of each event are not limited to the examples listed here.
When does the custom event appear? | Use cases |
|
|
|
|
|
|
|
|
Listening to events with addEventListener()
Below is an example of how to use the method addEventListener() with an Octane AI custom event.
document.addEventListener('octane.quiz.completed', function (e) {console.log('completed'); console.log(e.detail);}, false);
This code follows the standard syntax of addEventListener():
addEventListener(type, listener, options)
Here's a detailed breakdown of the example.
Keyword | Explanation |
| This is the target DOM element that the event listener is being attached to. |
| This method adds an event listener to the target element, defined here by |
| This string is the name of the custom event that is being targeted.
To listen for a different event, replace this with another string that represents the target custom event. |
| This is a callback function being used as the |
| This is an optional parameter that has been included for clarity.
Javascript events are propagated in two phases:
In the bubbling phase, events propagate from the target element to the farthest element (for example: child -> parent -> grandparent).
|
Octane AI events are configured for bubbling up and information about each item can be accessed through the detail object property. In the example above, e.detail.answers would contain all quiz answers chosen in a session.
A more detailed explanation of addEventListener() including descriptions of all valid parameters can be found in this MDN web document.
Event output example for octane.quiz.completed
Inside of Octane AI's quiz editor, you can find an example of what kind of output you might see when console logging the output of the octane.quiz.completed event.
This example is displayed below but can also be viewed in Octane AI's quiz editor by going to:
Settings -> Developer tools -> Results page behavior
The exact output of each octane.quiz.completed event listener will be unique to each quiz based on the quiz content, products recommended and more.
While the sample output can be reliably used to plan out your listener function, we recommend testing the event listener with a content-complete version of the target quiz.
document.addEventListener('octane.quiz.completed', function (e) {
// your code for building and handling the results page
console.log(e.detail);
/* output example
{
"quiz_wrapper_element": element, "answers": { "Question 1": "Answer 1", "Question 2": "Answer 2",
"quiz_wrapper_element": element,
"product_blocks": [
[
{
"description": "The candy bar of your dreams",
"id": "40597157904591",
"image": "https://cdn.shopify.com/s/files/...2048x2048.jpg?v=1639095",
"link": "https://store.myshopify.com/products/chocolate?variant=904591",
"price_formatted": "$5",
"tags": [
"brand new"
],
"title": "Crispy chocolate bar",
"type": ""
},
{
"description": "The everlasting taste you were looking for",
"id": "40597156823247",
"image": "https://cdn.shopify.com/s/files/...2048x2048.jpg?v=163968",
"link": "https://store.myshopify.com/products/lollipop?variant=459715",
"price_formatted": "3",
"tags": ["brand new", "birthday"],
"title": "Lollipop",
"type": ""
}
]
]
"quiz_results_url": "", "email": "", "phone": "", "user": ""
}
*/
}, false);
Event output example for add to cart events
The example below is a template for getting started with customizing add to cart behavior.
document.addEventListener('octane.quiz.addToCart', function (e) {
// your code for successfully added items
console.log(e.detail); // example: {items: [{id: '12345', quantity: 1}]}
}, false);
document.addEventListener('octane.quiz.addToCartError', function (e) {
// your code for the error case
}, false);
Listening to both events will help catch instances where the ATC button is not behaving as intended.
Frequently asked questions
Where do I add the
addEventListener()method?
The best place to add this method will be unique to each implementation. The simplest way is adding the event listener to the same area where you add the quiz embed code using a script tag:
<script type="text/javascript"> document.addEventListener('octane.quiz.completed', function (e) { console.log('completed'); console.log(e.detail); }, false); </script>
If addEventListener() is placed on a different page, you may need to use certain techniques (like reading Octane AI's cookie) to be able to listen for the event.
How do I do ________ with the custom event?
Implementation of the addEventListener() method beyond the examples shown in this article will require a certain level of proficiency with Javascript and/or core programming concepts.
While Octane AI is not able to offer instructions on how to implement code, our support team is happy to answer questions about any of the content in our documentation.
The custom event I need isn't available
If you'd like to see a new custom event implemented, you can request it through Octane AI's support team.
Custom events aren't able to be added immediately on request, but may be added in a future update!