Adding custom JavaScript to the quiz
For developers experienced with JavaScript, Lantern Product Quiz Builder offers a powerful suite of events and functions that can be used to enhance quiz interactivity and data handling. This guide explores these capabilities, detailing each event and function.
1. Where/how to add custom Javascript code
Lantern has a custom Tracking Code section under Settings where you can input any JavaScript code. To start, click Edit Quiz, and go to Settings.
We have 2 separate sections- one for code that should be inserted in the head of the page and one for code that should be added to the body of the page.
Please note: For optimal performance and reliability of your JavaScript customizations in the Lantern Product Quiz Builder, it is recommended to place your JavaScript code in the body section of the Tracking code input box, rather than in the header.
2. JavaScript Events in Lantern
2.1. lantern:reach_results_page
- Triggered: When the results page is reached but before any results are displayed.
- Use case: Ideal for redirections or pre-result manipulations.
1window.addEventListener("lantern:reach_results_page", () => {
2 window.location.href = "https://alternative-website-for-results.com";
3});
2.2. lantern:display_results
- Triggered: When the quiz results are ready to be displayed.
- Properties:
- email : Email address of the user (if provided).
- first_name : First name of the user (if provided).
- marketing_consent : Whether the user has consented to marketing.
- results : Array of product recommendations.
- content_block_results : Results from content blocks.
- answers : Answers given by the user (only answers with a name are available; assign a Property ID to each question in the quiz builder).
1window.addEventListener("lantern:display_results", (e) => {
2 const { results, content_block_results, answers, email, first_name, marketing_consent } = e.detail;
3 console.log({ results, content_block_results, answers, email, first_name, marketing_consent});
4 console.log(`${first_name} provided their email address: ${email} and has${marketing_consent === "YES" ? "" : " not"} agreed to receive marketing emails.`);
5 for(const result of results) {
6 console.log(`Recommended product: ${result.product.title}`);
7 }
8});
9
This code will display the available properties in your browser's console, allowing you to inspect the quiz data in real-time.
2.3. lantern:display_question
- Triggered: When any quiz page is displayed.
- Properties:
- id : Unique identifier of the page.
- title : Title of the page.
- description : Description of the page.
- type : Type of page (e.g., question, email capture).
- options : Available options for the question.
- isRequired : Whether the response to the page is required.
1window.addEventListener("lantern:display_question", (e) => {
2 const { id, title, description, type, options, isRequired } = e.detail;
3 console.log({ id, title, description, type, options, isRequired });
4});
This code will display the available properties for the question in your browser’s console.
The Question ID allows you to add custom JavaScript that runs only on specific questions within a quiz. Here's how you can add custom JavaScript for specific questions:
- Ensure the quiz is already published; question IDs change each time the quiz is republished, but they remain stable if no structural changes are made.
- Go to the question you want to target and note its unique ID.
- Use the lantern:display_question event listener, which listens for each question display. The code checks if the question ID matches the targeted question. Here’s an example code snippet that displays a warning before the corresponding question is loaded:
1<script>
2window.addEventListener("lantern:display_question", (e) => {
3 if (e.detail.id === "b6d70b05-6023-4d42-9756-02883d03a1cc") {
4 alert("custom javascript that only runs for this question");
5 }
6});
7</script>
- Make sure to replace "b6d70b05-6023-4d42-9756-02883d03a1cc" with the actual ID of your target question. Any JavaScript within this if block will only run for the specified question.
- Simply saving the JavaScript changes on the Settings page does not require republishing the quiz, keeping the question IDs stable.
- Here’s the warning you should expect to see on the front-end for the example code provided:
Please note: If you change the quiz structure (e.g., adding or removing questions), republishing is required, which will update the question IDs. Adjust any targeted IDs in your code if republishing occurs.
2.4. lantern:submit_answer
- Triggered: When an answer is submitted.
- Properties:
- id, title, description, type, options, isRequired : Identical to display_question.
- answers : Array of submitted answers.
- Additional properties on email capture pages:
- email : Email address of the user.
- first_name : First name of the user.
- marketing_consent : Marketing consent status.
1window.addEventListener("lantern:submit_answer", (e) => {
2 const { answers, email, first_name, marketing_consent } = e.detail;
3 console.log({ answers, email, first_name, marketing_consent });
4});
This code will show the available properties for the answer(s) in your browser’s console.
3.JavaScript Functions in Lantern
3.1. window.lantern.addAllToCart()
- Asynchronously adds all recommended products to the shopping cart. This function is particularly useful for dynamic content blocks with product recommendations. Note that products requiring variant selection cannot be added automatically.
1async function handleAddAllToCart() {
2 await window.lantern.addAllToCart();
3 console.log("All products added to cart.");
4}3.2. window.lantern.goToCart()
- Opens the shopping cart
pagein a new tab. This function is used immediately after addAllToCart to direct users to review their cart, enhancing the shopping experience.
1function openCart() {
2 window.lantern.goToCart();
3}3.3. window.lantern.restartQuiz()
- Resets the quiz to its beginning, enabling users to retake the quiz without reloading the page. This function is especially valuable for developers to integrate within their custom JavaScript implementations, ensuring users can start over smoothly.
1function restartQuiz() {
2 window.lantern.restartQuiz();
3}3.4. window.lantern.closeQuiz()
- Closes the quiz interface. This function mimics the action of the quiz's close button and is useful for developers who want to programmatically end the quiz experience from custom scripts.
1
2function closeQuiz() {
3 window.lantern.closeQuiz();
4}
For any questions or enquiries please contact our support team.