Skip to main content
Sends a quiz conversion event to Constructor.io’s API. This tracks when a user performs a conversion action (like adding to cart) on an item that was recommended through a quiz.

​
Method Signature

constructorio.tracker.trackQuizConversion(parameters, networkParameters?)

​
Parameters

​
parameters
object
required
Parameters for the quiz conversion event
​
networkParameters
object
Optional parameters for the network request

​
Returns

Returns true on success or an Error object if validation fails.

​
Examples

​
Basic Example

import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';

const constructorio = new ConstructorIOClient({
  apiKey: 'YOUR_API_KEY',
});

// Track quiz conversion (add to cart)
constructorio.tracker.trackQuizConversion({
  quizId: 'coffee-quiz',
  quizVersionId: '1231244',
  quizSessionId: '3123',
  itemId: 'COFFEE-001',
  itemName: 'Premium Espresso',
});

​
Complete Example

// Track quiz conversion with all parameters
constructorio.tracker.trackQuizConversion({
  quizId: 'coffee-quiz',
  quizVersionId: '1231244',
  quizSessionId: '3123',
  itemId: 'COFFEE-001',
  itemName: 'Premium Espresso',
  variationId: 'COFFEE-001-12OZ',
  revenue: '24.99',
  type: 'add_to_cart',
  section: 'Products',
});

​
Add to Wishlist Example

// Track add to wishlist from quiz
constructorio.tracker.trackQuizConversion({
  quizId: 'style-finder',
  quizVersionId: '2.0',
  quizSessionId: 'session-xyz',
  itemId: 'DRESS-456',
  itemName: 'Summer Dress',
  type: 'add_to_wishlist',
  revenue: '89.99',
});

​
Custom Conversion Type Example

// Track custom conversion from quiz
constructorio.tracker.trackQuizConversion({
  quizId: 'product-matcher',
  quizVersionId: '1.5',
  quizSessionId: 'session-abc',
  itemId: 'ITEM-789',
  itemName: 'Recommended Product',
  type: 'request_sample',
  isCustomType: true,
  displayName: 'Sample Requested',
});

​
Integration Example

// Track when user adds quiz-recommended item to cart
const addToCartButton = document.querySelector('.add-to-cart');
const quizData = window.quizSessionData; // Stored from quiz results

addToCartButton.addEventListener('click', () => {
  const itemId = addToCartButton.dataset.itemId;
  const itemName = addToCartButton.dataset.itemName;
  const price = addToCartButton.dataset.price;
  const variationId = document.querySelector('.variant-select').value;
  
  // Only track if this came from a quiz
  if (quizData) {
    constructorio.tracker.trackQuizConversion({
      quizId: quizData.quizId,
      quizVersionId: quizData.versionId,
      quizSessionId: quizData.sessionId,
      itemId: itemId,
      itemName: itemName,
      variationId: variationId,
      revenue: price,
      type: 'add_to_cart',
    });
  }
  
  // Add item to cart...
});

​
Complete Flow Example

// Complete quiz tracking flow
let quizSessionData = null;

// 1. After quiz completion
async function completeQuiz(quizId, answers) {
  const response = await constructorio.quizzes.getQuizResults(
    quizId,
    answers
  );
  
  // Store quiz session data
  quizSessionData = {
    quizId: response.quiz_id,
    versionId: response.quiz_version_id,
    sessionId: response.quiz_session_id,
  };
  
  // Display results...
}

// 2. User clicks a result
function handleResultClick(itemId, itemName) {
  if (quizSessionData) {
    constructorio.tracker.trackQuizResultClick({
      quizId: quizSessionData.quizId,
      quizVersionId: quizSessionData.versionId,
      quizSessionId: quizSessionData.sessionId,
      itemId: itemId,
      itemName: itemName,
    });
  }
}

// 3. User converts (adds to cart)
function handleAddToCart(itemId, itemName, price) {
  if (quizSessionData) {
    constructorio.tracker.trackQuizConversion({
      quizId: quizSessionData.quizId,
      quizVersionId: quizSessionData.versionId,
      quizSessionId: quizSessionData.sessionId,
      itemId: itemId,
      itemName: itemName,
      revenue: price,
      type: 'add_to_cart',
    });
  }
  
  // Add to cart...
}

​
When to Use

Call trackQuizConversion() when:
  • A user adds a quiz-recommended item to their cart
  • A user adds a quiz-recommended item to their wishlist
  • A user performs any conversion action on a quiz result
  • A user “likes” or “favorites” a quiz-recommended product

​
Important Notes

  • All three quiz identifiers are required: quizId, quizVersionId, and quizSessionId
  • Either itemId or itemName must be provided
  • These identifiers should match those used in trackQuizResultClick
  • The revenue parameter should be a string (not a number)
  • Default conversion type is "add_to_cart"

​
Standard Conversion Types

Common conversion types:
  • "add_to_cart" (default) - Item added to shopping cart
  • "add_to_wishlist" - Item added to wishlist
  • "add_to_favorites" - Item favorited

​
Custom Conversion Types

You can track custom conversion types: 
constructorio.tracker.trackQuizConversion({
  quizId: 'style-quiz',
  quizVersionId: '1.0',
  quizSessionId: 'session-123',
  itemId: 'ITEM-456',
  itemName: 'Styled Outfit',
  type: 'save_to_lookbook',
  isCustomType: true,
  displayName: 'Saved to Lookbook',
});

​
Revenue as String

Note that revenue must be a string: 
// Correct
revenue: '29.99'

// Also correct (convert number to string)
revenue: (29.99).toString()

// Incorrect
revenue: 29.99  // This will cause an error

​
Session Data Persistence

Consider storing quiz session data for the duration of the user’s session: 
// Store in sessionStorage
sessionStorage.setItem('quizData', JSON.stringify({
  quizId: 'coffee-quiz',
  versionId: '1.0',
  sessionId: 'session-abc',
}));

// Retrieve when needed
const quizData = JSON.parse(sessionStorage.getItem('quizData'));
if (quizData) {
  constructorio.tracker.trackQuizConversion({
    quizId: quizData.quizId,
    quizVersionId: quizData.versionId,
    quizSessionId: quizData.sessionId,
    itemId: 'ITEM-123',
    revenue: '29.99',
  });
}

​
Relationship with Other Events

Track these events in sequence:
  1. Quiz questions answered
  2. Quiz results displayed
  3. trackQuizResultClick - When user clicks a result
  4. trackQuizConversion - When user converts (this method)
  5. trackPurchase - When order is completed

​
API Endpoint

This method sends a POST request to: 
/v2/behavioral_action/quiz_conversion

Build docs developers (and LLMs) love

Get started for freeTalk to us