> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

1. **Include the script** — load `voyado.js` via GTM or a `<script>` tag.
2. **Add HTML containers** — place `<div>` elements with the right CSS class and `data-product-id` where you want widgets.
3. **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.             |

<Tip>
  Always integrate and verify on staging first. Once the setup is confirmed working, switch the script URL to production for your go-live.
</Tip>

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

```html theme={null}
<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**

```html theme={null}
<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**

```html theme={null}
<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**

```html theme={null}
<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.

```html theme={null}
<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.

<Tip>
  **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.
</Tip>

### 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:**

```html theme={null}
<script>
voyado('load-widgets', ['stars', 'highlights']);
</script>
```

**Product detail pages:**

```html theme={null}
<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:

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

## Widget Containers (HTML)

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.

<Tip>
  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**)
</Tip>

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

```html theme={null}
<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.

```html theme={null}
<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.

### Badge (PDP — sidebar)

Large numeric score, stars, review count, and a "Review this product" CTA that opens the review popup.

```html theme={null}
<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.

```html theme={null}
<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.

```html theme={null}
<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.

```html theme={null}
<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:**

```js theme={null}
voyado('load-widgets', ['stars', 'highlights']);
```

**PDP:**

```js theme={null}
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:

```js theme={null}
// 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.

```css theme={null}
: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

```css theme={null}
: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       |