The Quizzes module provides methods to build interactive product recommendation quizzes that guide users to relevant products through a series of questions.
Getting Started The quizzes module is available on your Constructor.io client instance:
const ConstructorioClient = require ( '@constructor-io/constructorio-client-javascript' ); const constructorio = new ConstructorioClient ({ apiKey: 'YOUR_API_KEY' , }); // Access the quizzes module constructorio . quizzes . getQuizNextQuestion ( 'beauty-quiz' );
Quiz Flow A typical quiz flow consists of:
Load First Question
Call getQuizNextQuestion without answers to get the first question
Collect Answers
Present questions to users and collect their responses
Get Next Questions
Pass collected answers to get subsequent questions
Retrieve Results
Call getQuizResults with all answers to get recommended products
Methods getQuizNextQuestion Retrieve the next question in a quiz based on previous answers.
First Question
Subsequent Questions
Preloading First Question
// Get the first question (no answers yet) constructorio . quizzes . getQuizNextQuestion ( 'beauty-quiz' , {}) . then (( response ) => { const { quiz_version_id , quiz_session_id , next_question } = response ; // Store these IDs for subsequent requests console . log ( next_question ); });
Parameters The unique identifier of the quiz (configured in your Constructor.io dashboard)
Additional parameters Array of answers in the format [[1,2], [0], ["true"], ["seen"], [""]] Answer format depends on question type:
Multiple choice : Array of selected option indices (e.g., [1, 2])Single choice : Array with one index (e.g., [0])Yes/No : Array with "true" or "false"Seen : Array with "seen"Skipped : Array with empty string [""] Version identifier for the quiz. Returned with the first request and should be passed with subsequent requests.
Session identifier for the quiz. Returned with the first request and should be passed with subsequent requests.
If true, tracking for this question will be skipped. Useful for preloading the first question.
getQuizResults Retrieve product recommendations and filter expressions based on quiz answers.
Basic Usage
With Pagination
With Filters
constructorio . quizzes . getQuizResults ( 'beauty-quiz' , { answers: [[ 1 , 2 ], [ 0 ], [ "true" ]], quizVersionId: 'v1' , quizSessionId: 'session-123' }) . then (( response ) => { console . log ( response . response . results ); });
Parameters The unique identifier of the quiz
Parameters including answers and optional refinements Array of all answers collected during the quiz in the format [[1,2], [0], ["true"]]
Version identifier for the quiz
Session identifier for the quiz
The page number of the results
The number of results per page to return
Key/value mapping of filters used to refine results
Options used for result formatting
Hidden metadata fields to return
getQuizResultsConfig Retrieve configuration for the results page of a quiz.
constructorio . quizzes . getQuizResultsConfig ( 'beauty-quiz' , { quizVersionId: 'v1' }) . then (( response ) => { console . log ( response ); });
Parameters The identifier of the quiz
Version identifier for the quiz
getQuizAllQuestions Retrieve all questions for a quiz at once (useful for showing quiz progress or building custom flows).
constructorio . quizzes . getQuizAllQuestions ( 'beauty-quiz' , { quizVersionId: 'v1' , quizSessionId: 'session-123' }) . then (( response ) => { console . log ( response . questions ); });
Parameters The identifier of the quiz
Version identifier for the quiz
Session identifier for the quiz
Complete Quiz Example class QuizManager { constructor ( quizId ) { this . quizId = quizId ; this . answers = []; this . versionId = null ; this . sessionId = null ; } async start () { // Get the first question const response = await constructorio . quizzes . getQuizNextQuestion ( this . quizId , {}); this . versionId = response . quiz_version_id ; this . sessionId = response . quiz_session_id ; return response . next_question ; } async answerQuestion ( answer ) { // Store the answer this . answers . push ( answer ); // Get next question const response = await constructorio . quizzes . getQuizNextQuestion ( this . quizId , { answers: this . answers , quizVersionId: this . versionId , quizSessionId: this . sessionId }); return response . next_question ; } async getResults () { // Get final recommendations const response = await constructorio . quizzes . getQuizResults ( this . quizId , { answers: this . answers , quizVersionId: this . versionId , quizSessionId: this . sessionId , resultsPerPage: 24 }); return response . response . results ; } } // Usage const quiz = new QuizManager ( 'beauty-quiz' ); // Start quiz const firstQuestion = await quiz . start (); displayQuestion ( firstQuestion ); // User answers question const nextQuestion = await quiz . answerQuestion ([ 1 , 2 ]); // Multiple choice displayQuestion ( nextQuestion ); // After all questions const results = await quiz . getResults (); displayResults ( results );
Multiple Choice
Single Choice
Yes/No
Skipped
User can select multiple options: // User selected options at index 1 and 2 answers : [[ 1 , 2 ]]
User selects one option: // User selected option at index 0 answers : [[ 0 ]]
Boolean response: // User answered "yes" answers : [[ "true" ]] // User answered "no" answers : [[ "false" ]]
User skipped the question: Events The quizzes module dispatches custom events on the browser window when requests complete:
window . addEventListener ( 'cio.client.quizzes.getQuizNextQuestion.completed' , ( event ) => { console . log ( event . detail ); }, false ); window . addEventListener ( 'cio.client.quizzes.getQuizResults.completed' , ( event ) => { console . log ( event . detail ); }, false ); window . addEventListener ( 'cio.client.quizzes.getQuizResultsConfig.completed' , ( event ) => { console . log ( event . detail ); }, false ); window . addEventListener ( 'cio.client.quizzes.getQuizAllQuestions.completed' , ( event ) => { console . log ( event . detail ); }, false );
Best Practices
Store quiz_version_id and quiz_session_id from the first request and pass them with all subsequent requests
Use skipTracking: true when preloading the first question for better UX
Track quiz completions and drop-off points to optimize your quiz flow
Allow users to skip questions or go back to previous questions
Show progress indicators to encourage completion
