Ratings and Reviews integration

Ratings and Reviews is an Engage feature that lets customers submit and view product ratings and reviews directly on your storefront. This guide covers how to add ratings and reviews widgets to your storefront using Voyado’s JavaScript SDK. It explains how to load the script via GTM or a script tag, place HTML containers on your page, and call load-widgets to render the right widget types per page. It also covers SPA handling and CSS custom properties for visual customization.

Quick Start

Three steps to get ratings and reviews on your site:

Include the script — load voyado.js 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.

Environments

Voyado provides two isolated environments. Each has its own script URL, backend, and data store — 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 on staging first. Once the setup is confirmed working, switch the script URL to production for your go-live.

Installation — via GTM (Recommended)

Most customers load voyado.js through Google Tag Manager. This keeps the script out of your codebase and lets you manage configuration, user identity, and widget loading entirely from GTM tags.

Load script, configure, and identify user

Create two Custom HTML tags in GTM that both fire on All Pages. The first loads the script and configures the session. The second identifies the logged-in user. Use the script URL that matches your target environment (see Environments). Staging: GTM tag: Voyado - Configuration 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>

GTM tag: Voyado - Login Staging

<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>

Production: GTM tag: Voyado - Configuration 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>

GTM tag: Voyado - Login Production

<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>

voyado() calls made before the script finishes loading are queued and replayed automatically, so tag ordering is not critical. Replace {{DL - ...}} with your own GTM Data Layer variables.

Add the stub to your page (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. It creates a queuing function that captures any calls made before voyado.js arrives, which the SDK replays automatically on bootstrap.

<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 anywhere on the page are then safe regardless of GTM load timing.

Why not just GTM?
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 (e.g. a DOM Ready trigger filtered by 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 widget types whose HTML containers exist on the current page.

SPA route changes (if applicable)

If your site is a Single Page Application, create a tag that fires on your virtual page-view trigger:

<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 are pure HTML — they cannot be injected by GTM. They must be part of your page templates.

For all widgets below (4.1–4.6), always set all of the following attributes on each container, in this order:

data-product-group-id (required)
data-product-id (required)
data-variant-id (required)

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:

data-product-group-id="SKU"
data-product-id="SKU-Green"
data-variant-id="SKU-Green-Small"

Stars (PLP — product cards)

Compact star rating for product listing pages. Supports multiple instances per page via the class selector.

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

Size variants: Add voyado-stars--small for 16 px stars (default is 40 px).

Ratings (PDP — inline)

Inline star + score + count. Typically placed near the product title.

<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. Large numeric score, stars, review count, and a “Review this product” CTA that opens the review popup.

<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, CTA hidden).

Summary (PDP)

AI-generated sentiment highlights from customer reviews. Automatically hidden when there are no reviews.

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

Reviews (PDP)

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.

<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.

Highlights (PLP / PDP)

A single AI-selected review excerpt with title, date, and “Powered by Voyado” footer. Lighter than the full Summary widget.

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

Loading Widgets

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

Call after the widget containers are in the DOM. Only list the widget types present on the current page — listing absent types wastes DOM searches. PLP:

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

PDP:

voyado('load-widgets', ['badge', 'ratings', 'summary', 'reviews']);

Available types: stars, ratings, badge, summary, reviews, highlights.

`voyado('reset-widgets')`

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

SPA Handling

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

// 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;
}

Key CSS classes for fine-grained 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