Skip to main content

Hue Technical Implementation Guide

Updated

Quick Start

To include a Hue module on your page, only 2 snippets of code are needed: a placeholder where the module should appear, and the Hue integration script which will replace the placeholder with the hue module.

Here is the snippet for the Hue integration script:

<script src="<https://app.poweredbyhue.app/js/integration.js>" defer></script>

Usually it is included right before the </body> tag, but it can be included anywhere on the page and it will work.

Then you add one or more placeholder snippets where you want Hue modules to appear on the page. Here are some examples:

<!-- snippet for the Video Review Module -->
<div id="hue-review-module"></div>

<!-- snippet for the Mini Video Review Module -->
<div id="hue-mini-review-module"></div>

Here is an example of a review module:

1.webp

And here’s an example of a mini review module:

2.webp

Once the snippets are added to the page, the Hue team will enable the modules and configure them according to your specifications. Hue can style the modules to match the look and feel of your website.

 

Setting the Product Id

On a Shopify product page, the module will automatically look up the correct productId. On other Shopify pages or other platforms, the module needs to know which product to use. You can specify the product id like this:

<div id="hue-mini-review-module" data-product-id="A123456"></div>

(You would use the your product id instead of A123456)

 

Shopify Implementation

If you use Shopify, you would be adding these changes to the code for your main theme and product page. These are located in your Shopify Admin dashboard.

  • Click on Online Store, then click on Themes.
  • We recommend creating a copy of your live theme and making the changes there first.
  • Choose the theme you would like to edit, click on Actions and then select Edit code.
  • Add the code snippets described in the quick start above
  • Save your changes

Shopify allows you to preview your theme and see your changes. When you are ready, you can publish the theme to make your public site reflect the changes.

 

Non-Shopify Implementation

Hue works with non-Shopify clients, with only small changes to the quick start steps:

  • In your codebase, locate the code that renders your page, and add the hue integration script and placeholder snippets there.
  • Your placeholder snippets will need to include a data-product-id attribute so Hue will know which product to use.

Usually these are the only differences. If there are any custom needs for your implementation, please reach out to the Hue team for assistance.

 

Module Options

The modules support some options to customize what product to show and on which device types they should appear:

data-product-id (optional on Shopify product pages, otherwise required)

  • if not set the module will attempt to automatically look up the id, which will only work on a Shopify product page
  • data-product-id="your_product_id" it will use the product id you specify. it should be the same id you use in the rest of your system
  • If you need a module that shows reviews for more than one product (eg. for a Homepage or Landing Page), the Hue team can provide a custom product id that will show the reviews of your choice. It would look like this: data-product-id="your_custom_placeholder"
  • If a module is not enabled for a product, it will not be displayed on the page at all, so it's safe to include the placeholder on all your product pages and it will only be visible on the ones that have reviews integrated.

data-device (optional) gives you flexibility to show different modules on different devices, which is helpful to show the modules that look best for that device's layout.

  • if not set the module will be displayed on all types of devices
  • data-device="desktop" the module will only display on desktop devices
  • data-device="mobile" the module will only display on mobile devices
  • if a device has a screen width >= 568px, it is considered a desktop device, otherwise it is considered a mobile device.

Here is an example of a review module with these attributes set:

<div id="hue-review-module" data-device="desktop" data-product-id="A123"></div>

 

Add to Cart

When a user clicks the add to cart button in a hue module, by default it will open Shopify's cart. If you are not using Shopify, or you need special handling for your cart, the Hue team can turn on a custom hue-add-to-cart event. Then you can respond to the event with your custom logic:

<script>
 document.addEventListener(
   'hue-add-to-cart',
   (e) => {
     // Your custom logic
     // Access the variant id using e.detail.variantId
   }
 )
</script>

Here is a more detailed example of typical code in a Shopify store that adds the item to the cart and then opens the cart. The Hue team can write custom code to suit your needs.

<script>
 document.addEventListener(
   'hue-add-to-cart',
   (e) => {
     // ADDS TO CART
     const formData = new FormData()
     formData.append('id', e.detail.variantId)
     formData.append('quantity', 1)
     formData.append('sections', 'cart,cart-count')
     fetch(window.Shopify.routes.root + "cart/add.js", {
       method: "POST",
       body: formData,
     })
       .then(e => e.json())
       .then(e => {
         // FINDS THE CART BUTTON AND CLICKS IT TO OPEN THE CART
         let element = document.querySelector("a[href='/cart']");
         element.click();

         // TELLS THE CART TO REFRESH WITH THE RESULTS OF THE ADD
         // SO THE USER WILL SEE THE ITEM THEY JUST ADDED IN THE CART
         document.dispatchEvent(new CustomEvent('cart:build' , {
           bubbles: true
         }));
         document.dispatchEvent(new CustomEvent('cart:refresh', {
           bubbles: true,
           detail: e
         }));
       })
   }
 )
</script>

 

Checkout Tracking

To analyze conversion rates - how often customers complete a purchase after interacting with a Hue module - you can set up checkout tracking. These instructions explain how to either grant the Hue team access to set it up, or how to set it up yourself:

Hue - Checkout Tracking Implementation

 

Dynamic Variant Filtering

When a customer chooses a shade or colorway of a product, the review module can react and show the most relevant reviews. Exact matches will come first, followed by reviews off by 1 shade, and then all other reviews. This is really nice for customers comparing similar variants of the product.

To enable this, the module listens for a hue-product-variant-changed event, and re-orders the reviews when it detects one. If you have code handling the shade selection, that is a good place to publish this event. Here is example code:

document.dispatchEvent(new CustomEvent('hue-product-variant-changed', {
 bubbles: true,
 detail: {
   variantId: newVariantId,
 }
}));

Alternatively, the Hue team can write code that reacts to changes in your product page that happen when the user chooses a shade, and publish the event that way. This code may need to be updated if you redesign your page.

 

FAQ

  • Does Hue impact my site speed?

    No. The Hue application runs independently of the storefront and all content is hosted on our servers so it does not impact site speed. Content is hosted using a CDN and optimized for performance.

  • What e-commerce platforms is Hue compatible with?

    Hue is compatible and fully supported with Shopify and Non-Shopify platforms. Please contact the Hue Team to discuss any custom needs.

  • How is my product information configured within the Hue app?

    The Hue Team has an internal administration portal for product configuration and management for our recommendation and matching system. Product information stays within Shopify.

  • How do I test the Hue app in a development environment?

    We recommend setting up the Hue app inside a copy of your Shopify theme or a development store for testing purposes.

  • Can Hue support my site traffic?

    At Hue, we strive for 99% uptime. We do so by continuously monitoring our systems for availability and performance. We have the ability to auto-scale our systems to support any increases in traffic.

 

Third Party Integration and Access

Please let the Hue team know if you would like to integrate with other third part apps such as:

  • Google Analytics — to compare analytics events across Hue and your site
  • Klaviyo / Listrak / other email CRM tools — to create email lists from users who enter their email through the Hue app

 

Data sent to Klaviyo/other providers

email: string
shopifyId: string
percentageMatch: string
productVariantId: number
hueTwins: { id: number }[]
customProperties?: Record<string, string | string[]>[]

customProperties may contain user attributes that were selected in process going through the quiz.

customProperties: [
  {"HUE_DEPTH": "medium"},
  {"HUE_[FOUNDATION|CONCEALER]_PREFERENCE": "exact-match"},
  {"HUE_SKIN_TYPE": ["oily"]},
  {"HUE_SKIN_CHARACTERISTIC": ["fine-lines/wrinkles", "freckles", "dark-spots"]},
  {"HUE_HAIR_COLOR": ["gray"]},
  {"HUE_EYE_COLOR": ["brown"]},
  {"HUE_[SHOPIFY_ID]_Shade Match": "[Variant Name]"},
  {"HUE_[Product Name]_Shade Match": "[Variant Name]"}
]

Example how data is stored in Klaviyo

4.webp

 

Google Analytics Integration

Please refer to this guide for steps to integrate with Google Analytics.

Related articles