# Embed reviews widgets

> Add the Cevoid script with your publishable key, place reviews widgets with the cevoid-reviews element and link to the review forms.

Breadcrumb: Widget › Reviews widgets · Updated: 2026-10-18
Docs index: https://docs.cevoid.com/developers/llms.txt

Reviews widgets show product and company reviews, star ratings and AI summaries on your storefront. They load through Cevoid's widget script, not the loyalty autoloader: one script per site, then one `<cevoid-reviews>` element per widget. You design each widget in Cevoid.

On Shopify, add reviews widgets as blocks in the theme editor through Cevoid's Reviews app for Shopify. Use the snippets below on any other platform and in headless storefronts.

## Prerequisites

- Reviews is part of your workspace's plan. Without it, widgets show no reviews.
- The widgets exist in Reviews → On-site widgets.
- Your publishable key, which starts with `cev_pk_`. The Embed widget dialog puts it in the script for you; it is also on Settings → Integrations → Cevoid API, see [Storefront API authentication](https://docs.cevoid.com/developers/storefront-api/authentication.md).

## Add the script

Paste the script right before the closing `</head>` tag, once per site, with your publishable key:

```html title="Cevoid script"
<script type="module" src="https://widget.cevoid.com/index.js" async data-cevoid-publishable-key="cev_pk_YOUR_KEY"></script>
```

The script loads nothing until a widget comes within 300 pixels of the viewport. It then loads the reviews code once for every reviews widget on the page, including widgets your app adds later.

## Add a widget

Copy a widget's element from its Embed widget dialog: go to Reviews → On-site widgets, open the widget and choose Embed widget, then Embed with code.

```html title="Product reviews on a product page"
<cevoid-reviews data-widget="w_4k8m2q7x1n5pza" data-product="auto"></cevoid-reviews>
```

| Attribute | What it does |
| --- | --- |
| `data-widget` | The widget's ID (`w_…`). Required. |
| `data-product` | The product a product widget shows: `auto`, a Cevoid ID or your own identifier. See [Products and pages](https://docs.cevoid.com/developers/widget/reviews-widgets#products-and-pages). |
| `data-collection`, `data-category`, `data-brand` | The collection, category or brand a widget shows, usually `auto`. |
| `data-scheme` | The color scheme: `primary`, `secondary`, `dark` or `accent`. You can change it after the widget has rendered. |
| `data-publishable-key` | A publishable key for this element only, when the script tag has none. |

The dialog adds the context attribute the widget needs. A widget made for a product, collection, category or brand renders nothing on an element without that attribute, and a widget made for a fixed selection of reviews renders nothing on an element with one.

## Widget types

| Type | What it shows |
| --- | --- |
| Review display | Reviews, in a layout you pick in Cevoid, such as a carousel or a ticker wall |
| Rating stars | The average rating and the number of reviews |
| Rating summary | A summary of the ratings |
| AI summary | An AI-written summary of the reviews |
| Product questions | A summary of the answers to your review form's product questions |

You choose in Cevoid whether a widget shows product reviews or company reviews; the element is the same.

## Products and pages

`data-product` accepts:

- `auto`: the product of the current page, matched by its URL, then by the last part of the URL path within the market.
- A Cevoid product or variant ID (`prd_…`, `var_…`).
- An absolute product URL, matched like `auto`.
- Your own identifier: a product or variant ID from your store (a Shopify numeric ID works), a SKU, a barcode or GTIN. When it matches more than one product, the widget shows nothing.

`data-collection="auto"` reads the collection from the page URL. `data-category="auto"` and `data-brand="auto"` read it from the URL, else from the product on the page.

## Link to the review forms

Review forms open from a link, so there is no element to paste. Add the query string to a page that has the Cevoid script:

```text title="Review form links"
https://your-store.com/products/linen-shirt?cevoid.widget=reviews.product-review
https://your-store.com/?cevoid.widget=reviews.product-review&cevoid.product=LINEN-SHIRT-M
https://your-store.com/?cevoid.widget=reviews.company-review
```

- On a product page, leave out `cevoid.product`: the form reads the product from the URL. Elsewhere, set it to a SKU or a Cevoid catalog ID.
- `cevoid.form` opens a specific form (`rfp_…` for product reviews, `rfc_…` for company reviews) instead of your default one.
- `rating=1` to `rating=5` fills in the star rating.

Cevoid reads these from the query string only, not from a `#` fragment.

## Rating events and rich snippets

When Rating stars render, they dispatch a `cevoid:widget-rendered` event that bubbles up from the `<cevoid-reviews>` element:

```js title="Listen for ratings"
document.addEventListener("cevoid:widget-rendered", (event) => {
  const { type, ratingValue, ratingCount } = event.detail
  if (type === "product-review-rating") console.log(ratingValue, ratingCount)
})
```

Rating stars and Rating summary also add Product JSON-LD with the rating to the page head, when the page shows one product with at least one review and has no product rating markup of its own. Search engines that do not run JavaScript miss it; to render the rating on your server, use [server-rendered rich snippets](https://docs.cevoid.com/developers/storefront-api/rich-snippets.md).

## Markets and language

Elements have no market or language attribute. Cevoid matches the page URL against the domains of your markets, else uses your default market, and the widget uses that market's language.

## Related articles

- [Authentication](https://docs.cevoid.com/developers/storefront-api/authentication.md)
- [Server-render rich snippets](https://docs.cevoid.com/developers/storefront-api/rich-snippets.md)
- [Cevoid widgets](https://docs.cevoid.com/developers/widget.md)

---

Canonical: https://docs.cevoid.com/developers/widget/reviews-widgets