Installing Quizzes on Headless Instances

Overview

Okendo Quizzes can not only recommend products to your customers but give you insights into respondant order attribution, attributed revenue and add to cart clicks. Add to cart events can be registered from either the quiz recommendation page within the Okendo quiz or after completion on the product display page if the customer has completed a quiz.

Quick Start Guide

A bare minimum headless implementation of Okendo Quizzes will require the following:

Inclusion of Okendo Quizzes

The Okendo Quizzes script must be loaded on any page that:

  • Will show a quiz, or

  • Will provide the ability to add a product to the cart, or

  • Can potentially place/confirms success of an order.

<script src="https://surveys.okendo.io/js/okendo-connect.quizzes.js" defer></script>

Implementation of required Integration Points

The following events must be handled and/or dispatched as part of any headless/custom cart implementation:

  • Enable Add to Cart functionality for products recommended by the quiz:

    • oke_quizCapture_addToCart

    • oke_quizCapture_addToCartSuccess

    • oke_quizCapture_addToCartFailure

  • Enable attribution of quiz response data and reporting in the Okendo backend:

    • oke_connect_cart_itemVariantAdded

    • oke_connect_checkout_orderSubmitted

See the relevant sections under Integration Points and Implementation Examples for further details and code samples.

Add a Quiz to a page

A quiz can be included on a page in one of two ways. We currently recommend that only one quiz is shown per page.

Embedded Quizzes

Once a quiz has been configured in the Okendo backend it can be embedded into any page with the Install Snippet. To retrieve the snippet for any given quiz:

  1. Navigate to the Quizzes section of the Okendo backend

  2. Locate the quiz in the Quiz List

  3. Click the “…” button to find the option to “Install” the quiz

  4. Reveal the installation instructions for an Embedded Section (click ”Show Install Instructions”)

  5. Copy the “Embed Quiz Snippet In Theme“ snippet and paste it into the desired location on the page

It should resemble the below:

<div oke-quiz oke-channel-quiz-id="..." oke-subscriber-id="..."></div>

Pop-up Quizzes

Merchants that prefer to show the Quiz in a pop up can use the showQuiz function available on okeConnectApi. See the relevant sections under Integration Points and Implementation Examples.

Integration Points

Add to Cart Functionality

Required for headless implementations

Merchants that have a custom cart implementation will need to notify Okendo Quizzes of whether a particular “Add to Cart” operation was successful or not. The dispatch of either a “success” or “failure” event will allow Okendo Quizzes to provide accurate visual feedback when a customer clicks “Add to Cart” on a recommended product.

  • oke_quizCapture_addToCart: Dispatched by Okendo. This event is used to notify you that a customer intends to “Add to Cart” one or more recommended products.

  • oke_quizCapture_addToCartSuccess: Dispatched by you. This event is used to visually indicate to customers that an “Add to Cart” operation succeeded.

  • oke_quizCapture_addToCartFailure: Dispatched by you. This event is used to visually indicate to customers that an “Add to Cart” operation failed.

Attribution & Buyer Behavior

Required for headless implementations

  • oke_connect_cart_itemVariantAdded: Dispatched by you. This event is used for the store to notify Okendo Quizzes when an add to cart event has occurred on the storefront. This event allows merchants to attribute data to the quiz response and feeds into reporting on quiz performance and buyer behavior.

  • oke_connect_checkout_orderSubmitted: Dispatched by you. This event is used for the store to notify Okendo Quizzes when an order is placed on the storefront. This event enables merchants to attribute the order with the quiz response, gathering valuable insights and feedback from customers to improve the overall effectiveness and relevance of the quizzes.

  • okendo_attribution_session_id: This attribute is added to cart attributes when the cart is created with the storefront API for the store to notify Okendo Quizzes when an order is processed on the storefront. This attribute enables merchants to attribute the order with the quiz response, gathering valuable insights and feedback from customers to improve the overall effectiveness and relevance of the quizzes.

  • okendo_quiz_response_id: This attribute is added to cart attributes when the cart is created with the storefront API for the store to notify Okendo Quizzes when an order is processed on the storefront. This attribute enables merchants to attribute the order with the quiz response, gathering valuable insights and feedback from customers to improve the overall effectiveness and relevance of the quizzes.

Here is an example implementation for the okendo_attribution_session_id and okendo_quiz_response_id attributes when updating cart attributes:

<script>
    const updateCartAttributesMutation = `
    mutation updateCartAttributes($attributes: [AttributeInput!]!, $cartId: ID!) {
        cartAttributesUpdate(attributes: $attributes, cartId: $cartId) {
            cart {
                id
                attributes{
                    key
                    value
                }
            }
            userErrors {
                field
                message
            }
        }
    }`;
    await client.request(updateCartAttributesMutation, {
        variables: {
        attributes: [{
            key: "okendo_quiz_response_id",
            value: "a8b5e430-6802-4084-a5af-c933c40164a5"
        },
        {
            key: "okendo_attribution_session_id",
            value: "d715e8bc-30d9-4867-a449-6c12b43baeb4"
        }],
        cartId: "gid://shopify/Cart/Z2NwLWFzaWEtc291dGhlYXN0MTowMUo0RlpRQ0NORUdZMkhDUlRCUzBKRlFYUg?key=508422975f2334d362ba2d81d2b1ef41"
        }
    });
</script>

Pop-up Quizzes

Optional

In place of embedding a quiz on a page with an app block or embed snippet, Merchants have the alternative option to display a quiz in a pop up at a time that suits for added flexibility.

  • showQuiz: Called by you. This function is used to display the quiz to the customer. By triggering this function at the appropriate time, merchants can engage customers and encourage them to interact with the quiz, resulting in a more interactive and personalized shopping experience.

Custom HTML

Optional

  • recommendedProductMounted: Provided by you, called by Okendo. This function is called when an individual product recommendation is mounted in the application. It can be used for inserting custom HTML or other custom product display functionality, allowing merchants to further customize the presentation of recommended products.

  • recommendedProductsMounted: Provided by you, called by Okendo. This function is called when all product recommendations are mounted in the application. It can be used for inserting custom HTML or other custom product display functionality for the entire recommendation page, providing merchants with the flexibility to tailor the appearance of the entire recommendation section.

Product Properties

Optional

  • generateCartLineItemProperties: Provided by you, called by Okendo. This event is triggered when a product is added to the cart from the recommendation page. It can be used to insert custom data into the cart line items, allowing merchants to enhance the cart experience with personalized information.

By leveraging the Quiz Frontend API, merchants can seamlessly integrate Okendo Quizzes and provide an engaging and personalized experience for their customers.

Implementation Examples

oke_quizCapture_addToCart Event Usage

The oke_quizCapture_addToCart event is used by Okendo Quizzes to notify the store that a customer intends to “Add to Cart” one or more recommended products.

An example implementation on how a custom cart might react to the oke_quizCapture_addToCart event:

<script>
	// Listen to the oke_quizCapture_addToCart event
		document.addEventListener('oke_quizCapture_addToCart', async event => {
	
		// Process each product variant to be added to the custom cart.
		for (const productVariant of event.detail.items) {
	
			try {
				// Attempt to add the variant.
				await customCart.addProductVariant({
					productId: productVariant.productId,
					variantId: productVariant.variantId,
					quantity: productVariant.quantity
				});
	
				// Tell Okendo Quizzes to visually show the customer
				// that the product variant was added successfully.
				document.dispatchEvent(new CustomEvent(
					'oke_quizCapture_addToCartSuccess',
					{	detail: { message: 'Yay! Added to cart successfully!' } }
				);
			}
			catch {
				// The variant was not able to be added to the custom cart.
				document.dispatchEvent(new CustomEvent(
					'oke_quizCapture_addToCartFailure',
					{	detail: { message: 'Oh no, something went wrong.' } }
				);
			}
		}
	
	});
</script>

oke_quizCapture_addToCartSuccess Event Usage

The oke_quizCapture_addToCartSuccess event is used for the store to notify Okendo Quizzes that an add to cart event was successfully processed (by your custom cart implementation).

Here is an example implementation for the oke_quizCapture_addToCartSuccess event:

<script>
    document.dispatchEvent(new CustomEvent('oke_quizCapture_addToCartSuccess', { 
        detail: { message: 'Added to cart!' }
    }));
</script>

oke_quizCapture_addToCartFailure Event Usage

The oke_quizCapture_addToCartFailure event is used for the store to notify Okendo Quizzes that your/a custom cart implementation failed to process an add to cart event.

Here is an example implementation for the oke_quizCapture_addToCartFailure event:

<script>
    document.dispatchEvent(new CustomEvent('oke_quizCapture_addToCartFailure', { 
        detail: { message: 'Could not add product to cart!' }
    }));
</script>

oke_connect_cart_itemVariantAdded Event Usage

The oke_connect_cart_itemVariantAdded event is used for the store to notify Okendo Quizzes when an add to cart event has occurred on the storefront. This is particularly useful for enabling attribution on headless implementations. This event allows merchants to attribute data to the quiz response and feeds into reporting on quiz performance and buyer behavior.

Here is an example implementation for the oke_connect_cart_itemVariantAdded event:

<script>
	const customCart = {
		addProductVariant: async ({ productId, variantId, quantity }) => {
	
				try {
					await addItemToCartBackend(productId, variantId, quantity);
	
					// Tell Okendo Quizzes to attribute add to cart data
					// to the quiz response to feed into reporting.
					document.dispatchEvent(new CustomEvent(
						'oke_connect_cart_itemVariantAdded',
						{
							detail: {
								productId: productVariant.productId,
								variantId: productVariant.variantId,
								quantity: productVariant.quantity
							}
						}				
					);
				}
				catch (error) {
					throw error;
				}
	
		}
	};
</script>

In the above implementation, the oke_connect_cart_itemVariantAdded event is dispatched using the document.dispatchEvent method. The event includes the following details:

  • productId (string): The unique identifier of the product added to the cart.

  • variantId (string): The unique identifier of the selected variant of the product.

  • quantity (number): The quantity of the product added to the cart.

By dispatching the oke_connect_cart_itemVariantAdded event with the relevant information, merchants can track add to cart events and associate them with the quiz response, providing valuable insights into the effectiveness of quizzes in driving buyer behavior.

Remember to replace 'your-product-id' and 'your-variant-id' with the actual product and variant IDs from your storefront.

By leveraging the oke_connect_cart_itemVariantAdded event provided by the Quiz Frontend API, merchants can seamlessly integrate Okendo Quizzes and gather valuable data on quiz performance and buyer behavior.

oke_connect_checkout_orderSubmitted Event Usage

The oke_connect_checkout_orderSubmitted event is used for the store to notify Okendo Quizzes when an order is placed on the storefront. This is particularly useful for enabling attribution on headless implementations. This event enables merchants to attribute the order with the quiz response, gathering valuable insights and feedback from customers to improve the overall effectiveness and relevance of the quizzes.

Here is an example implementation for the oke_connect_checkout_orderSubmitted event:

<script>
	// Dispatch the oke_connect_checkout_orderSubmitted event
	document.dispatchEvent(new CustomEvent('oke_connect_checkout_orderSubmitted', {
	  detail: {
	    cartToken: 'your-cart-token',
	    checkoutToken: 'your-checkout-token',
	    orderId: 'your-order-id',
	    products: [
	      {
	        productId: 'your-product-id',
	        variantId: 'your-variant-id',
	        quantity: 1
	      },
	      // Add more products as needed
	    ]
	  }
	}));
</script>

In the above implementation, the oke_connect_checkout_orderSubmitted event is dispatched using the document.dispatchEvent method. The event includes the following details:

  • cartToken (string)(optional): The token representing the user's cart.

  • checkoutToken (string)(optional): The token representing the user's checkout session.

  • orderId (string)(optional): The unique identifier of the order placed on the storefront.

  • products (array of objects): An array of products included in the order, where each object contains the following details:

    • productId (string): The unique identifier of the product.

    • variantId (string): The unique identifier of the selected variant of the product.

    • quantity (number): The quantity of the product added to the cart.

By dispatching the oke_connect_checkout_orderSubmitted event with the relevant information, merchants can link the order with the quiz response, gaining insights into the impact of quizzes on customer purchasing behavior.

Remember to replace 'your-cart-token', 'your-checkout-token', 'your-order-id', 'your-product-id', and 'your-variant-id' with the actual tokens, order ID, product ID, and variant ID from your storefront.

By leveraging the oke_connect_checkout_orderSubmitted event provided by the Quiz Frontend API, merchants can seamlessly integrate Okendo Quizzes and gather valuable data on the impact of quizzes on customer orders.

showQuiz Function Usage

The showQuiz event can optionally be used to trigger display of Okendo Quizzes on your storefront in a modal. By triggering this event at the appropriate time, you can display the quiz to your customers and create a more interactive and personalized shopping experience. Here is an example implementation for the showQuiz event:

<script>
	window.okeConnectApi.showQuiz(channelQuizId, subscriberId);
</script>

In the above implementation, the showQuiz event takes two parameters:

  • channelQuizId (string): The unique identifier of the quiz channel. You can find this ID in the install dialogue of the quiz you want to display in the Okendo admin application.

  • subscriberId (string): Your Okendo subscriberId.

Once you have implemented the showQuiz event, you can call it at the appropriate time in your storefront's code to display the quiz to your customers.

Remember to customize the appearance and behavior of the quiz to align with your branding and provide an engaging experience for your customers.

By leveraging the showQuiz event provided by the Quiz Frontend API, you can seamlessly integrate Okendo Quizzes and enhance the overall shopping experience for your customers.

A sample custom liquid snippet for a button that shows the quiz in a popup

<a  
  href="#" 
  onclick="okeConnectApi.showQuiz('your-channel-quiz-id', 'your-subscriber-id')" 
  class="button button--full-width">Take our quiz
</a>

recommendedProductMounted Function Example

The recommendedProductMounted event is triggered when an individual product recommendation is mounted in the application. It provides an opportunity for merchants to insert custom HTML or other custom product display functionality, allowing them to further customize the presentation of recommended products. Here is an example implementation for the recommendedProductMounted event and using it to insert an additional product option selector:

<script>
	window.okeConnectApi.recommendedProductMounted = (sectionContent, product) => {
		const addButton = sectionContent.querySelector('button.c-addToCart');
		if (addButton && !sectionContent.loaded) {
			sectionContent.loaded = true;
			let selectorHtml = `
			<div class="c-resultLearnMore">
				<a class="c-resultButton-primary c-button c-resultButton" style="width: 100%;" href="https://sample.myshopify.com/collections/product1" target="_blank">Learn More</a>
			</div>`;
			addButton.insertAdjacentHTML('beforeBegin', selectorHtml);
		}
	};
</script>

In the above implementation, the recommendedProductMounted event provides the following:

  • sectionContent(html): The html content that will be rendered for the recommended product.

    For example:

    <div class="c-recommendedProduct">
    <a
        href="<https://okendo-seahorse-emporium.myshopify.com/products/red-seahorse>"
        data-productid="shopify-7571259490550"
        target="_blank"
    >
        <img
            alt="Red Seahorse"
            src="<https://cdn.shopify.com/s/files/1/0629/4234/7510/products/GettyImages-1159240457-79e9779a466c4b6e82d188384c34142b.jpg?v=1645164970>"
            class="c-recommendedProduct-image"
        >
    </a>
    <div class="c-recommendedProduct-nameAndPrice">
        <div class="c-recommendedProduct-name u-marginTop--small u-marginBottom--xSmall"><a
                href="<https://okendo-seahorse-emporium.myshopify.com/products/red-seahorse>"
                target="_blank"
            >Red Seahorse</a>
        </div>
        <div class="c-recommendedProduct-price u-marginBottom--medium"><a
                href="<https://okendo-seahorse-emporium.myshopify.com/products/red-seahorse>"
                target="_blank"
            >$10.00</a>
        </div>
    </div>
    <button
        class="c-resultButton-secondary c-button c-resultButton c-addToCart"
        id="shopify-7571259490550-0"
        style="width: 100%;"
    >
        <span class="c-addToCart-text">Add to Cart</span>
    </button>
</div>

  • product (json): A JSON object representing the recommended product and associated properties.

    For example:

    {
    "productId": "shopify-7571259490550",
    "imageUrl": "<https://cdn.shopify.com/s/files/1/0629/4234/7510/products/GettyImages-1159240457-79e9779a466c4b6e82d188384c34142b.jpg?v=1645164970>",
    "name": "Red Seahorse",
    "url": "<https://okendo-seahorse-emporium.myshopify.com/products/red-seahorse>",
    "options": [
        {
            "name": "Title",
            "values": [
                "Default Title"
            ]
        }
    ],
    "variants": [
        {
            "variantRemoteId": "42585640960246",
            "title": "Default Title",
            "price": 10,
            "currencyCode": "AUD",
            "availableForSale": true,
            "imageUrl": "<https://cdn.shopify.com/s/files/1/0629/4234/7510/products/GettyImages-1159240457-79e9779a466c4b6e82d188384c34142b.jpg?v=1645164970>"
        }
    ],
    "addToCartButtonId": "shopify-7571259490550-0",
    "isVariantRecommendation": false,
    "selectedVariant": {
        "variantRemoteId": "42585640960246",
        "title": "Default Title",
        "price": 10,
        "currencyCode": "AUD",
        "availableForSale": true,
        "imageUrl": "<https://cdn.shopify.com/s/files/1/0629/4234/7510/products/GettyImages-1159240457-79e9779a466c4b6e82d188384c34142b.jpg?v=1645164970>"
    },
    "variantSelectorId": "aafbcd30-837d-479a-83ab-654ab1faacac"
}

By implementing the recommendedProductMounted event, merchants can customize the appearance and behavior of individual recommended products, providing a tailored and personalized shopping experience for their customers.

recommendedProductsMounted Function Example

The recommendedProductsMounted event is triggered when all product recommendations are mounted in the application. It provides an opportunity for merchants to insert custom HTML or other custom product display functionality for the entire recommendation page. This allows merchants to have full control over the presentation of the entire recommendation section. Here is an example implementation for the recommendedProductsMounted event:

<script>
	window.okeConnectApi.recommendedProductsMounted = (recommendationSection, products) => {
	    // Insert custom HTML or other custom product display functionality for the entire recommendation page
	    // Example:
	    recommendationSection.insertAdjacentHTML('beforeend', '<div class="custom-recommendation-section">...</div>');
	};
</script>

In the above implementation, the recommendedProductsMounted event provides the following:

  • recommendationSection (html): The html element representing the entire recommendation section.

  • products (json): A JSON object representing all recommended products to be displayed on the recommendation page.

By implementing the recommendedProductsMounted event, merchants have the flexibility to insert custom HTML or other custom product display functionality for the entire recommendation page. This allows for a highly customizable and tailored shopping experience for their customers.

generateCartLineItemProperties Function Example

The generateCartLineItemProperties event is triggered when a product is added to the cart from the recommendation page. It provides an opportunity for merchants to insert custom data into the cart line items, allowing them to enhance the cart experience with personalized information. Here is an example implementation for the generateCartLineItemProperties event:

<script>
	window.okeConnectApi.generateCartLineItemProperties = (addToCartButtonId, product) => {
	    // Insert custom data into the cart line items
	    // Example:
	    const customProperties = {};
	    customProperties['Customer option'] = 'Some custom option';
	    customProperties['_has_custom'] = true;
	    return customProperties;
	};
</script>

In the above implementation, the generateCartLineItemProperties event provides the following:

  • addToCartButtonId(string): id of the add to cart button element that was clicked.

  • product (json): A JSON object representing the product that was added to the cart from the recommendation page.

By implementing the generateCartLineItemProperties event, merchants can enrich the cart experience by including custom properties for each line item. This allows for a more personalized and tailored shopping experience for their customers.

PreviousStores Running an Existing Vue AppNextOkendo Shopify Hydrogen Support

Last updated