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" data-product-id="A123456"></div> <!-- snippet for the Mini Video Review Module --> <div id="hue-mini-review-module" data-product-id="A123456"></div>
Here is an example of a review module:
And here’s an example of a mini review module:
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
The module needs to know which product to use. You can specify the product id like using the data-product-id attribute like this:
<div id="hue-mini-review-module" data-product-id="A123456"></div>
(You would use your product id instead of A123456)
Implementation
Hue is platform agnostic and can work with any setup:
- 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.
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 (required)
- 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.
data-hue-main-title(optional) gives you possibility to manage your module title.
Here is an example of a review module with these attributes set:
<div id="hue-review-module" data-device="desktop" data-product-id="A123" data-hue-main-title="My new title"></div>
Add to Cart
When a user clicks the add to cart button in a hue module, it will send a custom hue-add-to-cart event. Then you can respond to the event with your custom logic. The Hue team can write custom code to suit your needs, most likely using a call to your existing add to cart functionality.
<script>
document.addEventListener(
'hue-add-to-cart',
(e) => {
// Your custom logic
// Access the variant id using e.detail.variantId
}
)
</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
Importing Products
It is possible to manually add products into Hue’s system, but most clients find it helpful to set up an automatic import. This can either be a one time import if the products will stay the same, or it can be a recurring import to keep up to date with changing products, availability and pricing.
Typically, you would provide this data via an API, product feed, or csv/json file. Our engineering team will work with you to set it up.
Here is the data type we use internally to import a product, if your data type includes these fields we can write an adapter. Optional fields have a ?
// If input can be converted into this data type, we can import it.
export type StandardizedProductInfo = {
product: StandardizedProduct
publishedAt?: Date
variants: StandardizedVariant[]
pageUrl: string // the pdp of the product
optionTypes?: StandardizedOptionType[]
options?: StandardizedOption[]
}
export type StandardizedProduct = {
extId: string // the product's id in your system
name: string
handle: string
assetUrl: string
}
export type StandardizedVariant = {
extId: string // the variant's id in your system
name: string
order: number // the order in which to display the variant
assetUrl: string
// There should be only one option of each type.
options?: StandardizedOption[]
// whether the variant is available for purchase (not required for importing)
available?: boolean
// the price for this variant (not required for importing)
price?: number // should be an int like 2399 for $23.99
compareToPrice?: number // should be an int like 2399 for $23.99
}
export type StandardizedOptionType = {
extId: string
label: string
}
// Either swatchColor or swatchUrl should be set
export type StandardizedOption = {
optionType: StandardizedOptionType
extId: string
displayText: string
swatchColor?: string
swatchUrl?: string
}
Dynamic Pricing
If you would like prices and availability of products to update dynamically, you can provide an API exposing this information, and a url where the Hue system can call it. Here is an example of the data type the system needs. A few notes to look out for:
- Price is x100 to avoid rounding errors
- There should be one entry in the variants array for each product variant
- “color” is used for the variant’s name
{
"data": [
{
"id": "112233",
"name": "Your Product Name",
"sku": "ABDCE123",
"color": "",
"available": true,
"price": 9900,
"currency": "USD",
"variants": [
{
"id": "112233-LB",
"sku": "ABDCE456",
"name": "Your Product Name",
"color": "Light Blue",
"size": "XS",
"available": true,
"price": 9900,
"currency": "USD",
"discounted": false,
}
]
}
]
}
Alternatively, UI elements that depend on pricing and availability can be hidden, such as the add to cart button. This is a good option when providing an API is not convenient.
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 all 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.
-
How do I test the Hue app in a development environment?
We recommend setting up the Hue app inside a copy of your 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 //if applicable
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_[STOREFRONT_ID]_Shade Match": "[Variant Name]"},
{"HUE_[Product Name]_Shade Match": "[Variant Name]"}
]
Example how data is stored in Klaviyo
Google Analytics Integration
Please refer to this guide for steps to integrate with Google Analytics.