Ratings and Reviews (BETA)

This feature is in beta. This means it might at any time be changed, withdrawn from your account, or become part of a paid add-on module. You might also experience interruptions of this service, degradation of user experience or faulty behavior even in critical processes such as automations and sendouts. Voyado welcomes feedback on beta features, and encourages you to try them, but you should not build business critical logic on beta features. Only when a feature reaches its full release can you trust it to function reliably with no further breaking changes.

Ratings and Reviews is an Engage feature that lets your customers submit and view product ratings and reviews directly on your storefront. This article covers:

How to add ratings and reviews widgets using Voyado’s JavaScript SDK
Single Page Application handling
CSS custom properties for further customization

Environments

Voyado provides you with two isolated environments. Each has its own script URL, backend, and data store meaning that nothing is shared between them.

Environment	Script URL	Purpose
Staging	`https://static.staging.onsite.voyado.com/widget/voyado.js`	Connected to your staging Voyado environment. Use for integration, testing, and QA.
Production	`https://static.onsite.voyado.com/widget/voyado.js`	Connected to your production Voyado environment. Live, customer-facing.

Always integrate and verify in the Staging environment first. Once the setup is confirmed to work there, switch to the Production URL for your go-live.

Setting up

The basic steps to get ratings and reviews on your site are:

Include the script — Load the voyado.js script via GTM or a <script> tag
Add HTML containers — Place <div> elements with the right CSS class and data-product-id where you want widgets
Call load-widgets — Tell the SDK which widget types to render

Most customers load the voyado.js script through Google Tag Manager. Doing it this way keeps the script out of your codebase and lets you manage configuration, user identity, and widget loading entirely via GTM tags. This is the recommended way to load the script.

The three steps above will now be considered in more detail.

1 - The scripts

Start by creating two Custom HTML tags in GTM that both fire on All Pages.

The first tag loads the script and configures the session
The second identifies the logged-in user

Use whatever script URL matches your target environment (see Environments above):

Show configuration script for Staging

<script>
(function(i,s,o,g,r,a,m){i['VoyadoObject']=r;i[r]=i[r]||function()
{(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();
a=s.createElement(o),m=s.getElementsByTagName(o)[0];
a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://static.staging.onsite.voyado.com/widget/voyado.js','voyado');

voyado('config', {
  locale: '{{DL - Locale}}'         // (optional) e.g. 'sv-SE' — falls back to browser language
});
</script>

<script>
voyado('login', {
  email: '{{DL - Email}}',           // (optional) logged-in customer email
  name: '{{DL - Name}}',             // (optional) logged-in customer name
  contactId: '{{DL - ContactId}}'    // (optional) logged-in Voyado contact ID
});
</script>

Show configuration script for Production

<script>
(function(i,s,o,g,r,a,m){i['VoyadoObject']=r;i[r]=i[r]||function()
{(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();
a=s.createElement(o),m=s.getElementsByTagName(o)[0];
a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://static.onsite.voyado.com/widget/voyado.js','voyado');

voyado('config', {
  locale: '{{DL - Locale}}'         // (optional) e.g. 'sv-SE' — falls back to browser language
});
</script>

<script>
voyado('login', {
  email: '{{DL - Email}}',           // (optional) logged-in customer email
  name: '{{DL - Name}}',             // (optional) logged-in customer name
  contactId: '{{DL - ContactId}}'    // (optional) logged-in Voyado contact ID
});
</script>

Here, replace {{DL - ...}} with your own GTM Data Layer variables.

All calls to voyado() made before the script finishes loading are queued and replayed automatically when the script is ready, so tag ordering here is not critical.

Adding queuing function (required)

The GTM tag above loads voyado.js asynchronously. This means your page code may call voyado('load-widgets', ...) before the script has finished loading, resulting in a ReferenceError: voyado is not defined. To prevent this, add the following minimal stub to your <head> before the GTM snippet. This creates a queuing function that captures any calls made before voyado.js arrives, which the SDK replays automatically on bootstrap.

See queuing function stub

<head>
  <!-- Voyado stub — install before GTM so page-level voyado() calls queue safely -->
  <script>
  window.voyado = window.voyado || function() {
    (window.voyado.q = window.voyado.q || []).push(arguments);
  };
  </script>

  <!-- Google Tag Manager -->
  ...
</head>

This is a one-time addition to your page template. All voyado() calls made anywhere on that page are then safe regardless of the GTM load timing.

GTM’s own initialization snippet (i[r]=i[r]||function()...) performs the same setup but only after gtm.js has downloaded. The stub above runs synchronously during HTML parsing, before any network requests, closing the race window.

Load widgets

Create additional Custom HTML tags for each page type. Fire them on the appropriate triggers (for example a DOM Ready trigger filtered by the page path).

Category / listing pages

<script>
voyado('load-widgets', ['stars', 'highlights']);
</script>

Product detail pages

<script>
voyado('load-widgets', ['badge', 'ratings', 'summary', 'reviews', 'rate']);
</script>

Only list the widget types whose HTML containers actually exist on the current page.

SPA route changes (if applicable)

If your site is a SPA (Single Page Application) then create a tag that fires on your virtual page-view trigger:

Single Page Application

<script>
voyado('reset-widgets');
// After the new view is rendered:
voyado('load-widgets', ['stars']);  // adjust per page type
</script>

Place <div> containers anywhere in your HTML. These containers must be pure HTML, they cannot be injected by GTM. They must be part of your page templates.

For all widgets below set all the following attributes on each container, in this order:

Attribute	Required	Description
`data-product-group-id`	Yes	Product group identifier (for variant grouping)
`data-product-id`	Yes	Product identifier
`data-variant-id`	Yes	Specific variant identifier

Example values are:

data-product-group-id = “SKU”
data-product-id = “SKU-Green”
data-variant-id = “SKU-Green-Small”

Here are the available widgets in more detail, along with where they are shown.

PLP = Product Listing Page
PDP = Product Detail Page

This is a compact star rating for product listing pages. Supports multiple instances per page via the class selector.

Stars widget

<div class="voyado-stars"
     data-product-group-id="SKU"
     data-product-id="SKU-Green"
     data-variant-id="SKU-Green-Small">
</div>

Variants:

Add voyado-stars--small for 16 px stars (default is 40 px)

This is an inline star \ score count. It is typically placed near the product title.

Ratings widget

<div class="voyado-ratings voyado-ratings--small"
     data-product-group-id="560R"
     data-product-id="560R-Strawberry"
     data-variant-id="">
</div>

Variants:

voyado-ratings--small (16 px text)
voyado-ratings--vertical (stacked layout)
Or both combined.

This includes a large numeric score, stars, a review count and a “Review this product” CTA that opens the review popup.

Badge widget

<div class="voyado-badge"
     data-product-group-id="SKU"
     data-product-id="SKU-Green"
     data-variant-id="SKU-Green-Small">
</div>

Variants:

voyado-badge--compact for a smaller score (48 px instead of 78 px with CTA hidden)

This includes AI generated sentiment highlights from customer reviews. It is automatically hidden when there are no reviews.

Summary widget

<div class="voyado-summary"
     data-product-group-id="SKU"
     data-product-id="SKU-Green"
     data-variant-id="SKU-Green-Small">
</div>

This is a full review list with sort dropdown, pagination, author, date, star rating, text, verified-buyer badge, thumbs up/down voting, and comment threads. Authenticated users can edit their own reviews.

Reviews widget

<div class="voyado-reviews"
     data-product-group-id="SKU"
     data-product-id="SKU-Green"
     data-variant-id="SKU-Green-Small">
</div>

Variants:

voyado-reviews--boxed wraps each review in a card

This is a single AI-selected review excerpt including title, date, and a “Powered by Voyado” footer. It is lighter than the full Summary widget.

Highlights widget

<div class="voyado-highlights"
     data-product-group-id="SKU"
     data-product-id="SKU-Green"
     data-variant-id="SKU-Green-Small">
</div>

Distribution (PDP — rating breakdown)

Five-row breakdown (5★ down to 1★), each row showing a mini star icon, the review count for that star value in parentheses, and a horizontal bar sized to that rating’s share of all reviews. This is the widget referenced internally as “rating breakdown (5★/4★/3★…).”

Distribution widget

<div class="voyado-distribution"
     data-product-group-id="g-w001"
     data-product-id="w001"
     data-variant-id="w001-xs-black">
</div>

Carousel (PDP — scrolling review cards)

A horizontally-scrolling row of review cards under the heading “What our customers are saying,” with prev/next nav buttons. Supports two optional filtering attributes not used by any other widget:

data-min-rating: Include only reviews at or above this star rating (for example, 4 means show only 4 and 5 star reviews)
data-max-review-count: Cap the number of review cards rendered (for exampple, 10)

Carousel widget

<div class="voyado-carousel"
     data-product-group-id="g-w001"
     data-product-id="w001"
     data-variant-id="w001-xs-black"
     data-min-rating="4"
     data-max-review-count="10">
</div>

Add Review (PDP — standalone collection button)

A standalone CTA button that opens the review-submission modal directly.

Add Review widget

<button class="voyado-add-review"
    data-product-group-id="g-w001"
    data-product-id="w001"
    data-variant-id="w001-xs-black">
  Add a review
</button>

3 - Loading widgets

This is how the widgets are loaded:

Loading widgets

voyado('load-widgets', [types])

You will replace [types] here by the list of widgets you want to load. Available are:

“stars”
“ratings”
“badge”
“summary”
“reviews”
“highlights”
“distribution”
“carousel”
“add-review”

PLP example

voyado('load-widgets', ['stars', 'highlights']);

PDP example

voyado('load-widgets', ['badge', 'ratings', 'summary', 'reviews', 'distribution', 'carousel', 'add-review']);

Make this call to load the widgets after the widget containers are in the DOM.. Only use the widget types that are present on the current page; listing absent types wastes DOM searches.

Clearing widgets

To clear the loaded widgets, call:

voyado('reset-widgets')

Call this before a SPA route change, then call load-widgets again after the new view is rendered.

Starting from zero

When starting off, when a product has no reviews and the goal is not to display but to start collecting, Voyado recommends using only the add-review widget and “Add Review” button. When there are no reviews, other display widget either will show an empty/zero state or hides themselves, which reads as broken or unfinished to a shopper. The “Add Review” button however works identically no matter how many reviews a product has. Once a product has a meaningful number of reviews, add the other display widgets. The “Add Review” button can still remain.

SPA Handling

If your site uses client-side routing (single page application), call reset-widgets before each navigation and then load-widgets after the new content is in the DOM:

SPA Handling

// Before navigating away
voyado('reset-widgets');

// After new view is rendered
voyado('load-widgets', ['badge', 'reviews']);

CSS Customization

All visual tokens are CSS custom properties on :root. Override them to match your brand.

:root {
  /* Colors */
  --voyado-rating: #66C1BF;               /* Filled star / accent */
  --voyado-neutral: #D8D8D5;              /* Empty star / dividers */
  --voyado-text: #333333;                 /* Body text */
  --voyado-cta-color: #437984;            /* CTA button background */
  --voyado-cta-text-color: #FFFFFF;       /* CTA button label */
  --voyado-review-interactions-color: #A7A7A7;
  --voyado-trophy-color: #E1C32E;
  --voyado-select-bg: #FFFFFF;
  --voyado-select-border-color: #E5E5E5;

  /* Typography */
  --voyado-font-family: "Helvetica", sans-serif;
  --voyado-font-size-large: 28px;
  --voyado-font-size-medium: 22px;
  --voyado-font-size-small: 16px;
  --voyado-font-size-micro: 12px;

  /* Star sizes */
  --voyado-star-size-large: 40px;
  --voyado-star-size-small: 16px;

  /* Spacing */
  --voyado-spacing-xs: 5px;
  --voyado-spacing-sm: 10px;
  --voyado-spacing-md: 20px;
  --voyado-spacing-lg: 40px;

  /* Accessibility */
  --voyado-focus-color: #005fcc;
  --voyado-focus-ring-width: 2px;
}

Brand override example

:root {
  --voyado-rating: #ff6b35;
  --voyado-cta-color: #4a90e2;
  --voyado-font-family: "Inter", sans-serif;
}

/* Or scoped to a wrapper */
.my-product-page {
  --voyado-rating: #FFD700;
}

CSS classes for overrides

Class	Element
`.voyado-star--filled`	Filled star SVG
`.voyado-star--half`	Half-filled star
`.voyado-star--empty`	Empty star SVG
`.voyado-ratings--value`	Numeric score text
`.voyado-ratings--count`	Review count text
`.voyado-badge--score`	Large numeric score
`.voyado-cta`	CTA button (Badge, Rate)
`.voyado-review--author`	Reviewer name
`.voyado-review--text`	Review body
`.voyado-review--interactions`	Thumbs + comment row
`.voyado-reviews--select`	Sort dropdown
`.voyado-summary--title`	AI summary heading

Contacts

Transactions

Orders

Loyalty

Product data

Elevate