# Embed review widgets

> Add review widgets to your store with Shopify theme blocks, or with the Cevoid script and one element per widget.

Breadcrumb: Reviews › Embed review widgets · Updated: 2026-10-20
Docs index: https://docs.cevoid.com/llms.txt

Embed a review widget to show it on your store. On Shopify, add it with a theme block in the theme editor, with no code. On other platforms, add the Cevoid script once, and an element wherever a widget goes.

Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) to embed your review widgets.

## How embedding works

A review widget on your store needs two things:

- **The Cevoid script:** Loaded once on the page. It loads nothing until a widget comes close to the visible part of the page. On Shopify, every block of the Reviews app loads it, and the app embed _Cevoid Reviews_ loads it on every page. See [Add the Cevoid script](https://docs.cevoid.com/reviews/showcase/embed-review-widgets#add-the-cevoid-script).
- **A placement:** A theme block or an element that carries the widget's ID, which starts with `w_`. A dynamic widget also gets the page's product, collection, category, or brand from its placement.

Everything else lives in the widget, so changing a widget never needs a change on your site.

Review widgets need a Reviews plan: see [Plans that include Reviews](https://docs.cevoid.com/reviews/setup/order-limit.md#plans-that-include-reviews).

## Add the Cevoid script

The Cevoid script goes on every page of your site, once: it loads your review widgets and the review form, which review request links open on the start page of the customer's market. Galleries, cards, and program widgets use scripts of their own: see [Add Cevoid's scripts](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md#add-cevoids-scripts). The Cevoid script's steps are in the _Install the Cevoid script_ dialog, which opens from **Script status** on [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets), and from **Add script** in _Things to do_ on [Reviews → Overview](https://app.cevoid.com/reviews).

**Shopify**

On Shopify, the Reviews app adds the script to every page of your theme with its app embed, _Cevoid Reviews_. No template needs editing.

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) and click **Script status**. The _Install the Cevoid script_ dialog opens.
2. Under _Install with Shopify_, click **Enable app embed**. The Shopify theme editor opens on _App embeds_, with _Cevoid Reviews_ turned on.
3. Click **Save** in the Shopify theme editor
4. Click **Check status** in the dialog. Each market shows _Installed_ once Cevoid finds the script.

If _Install with Shopify_ shows _App required_, your store doesn't have the Reviews app, _Cevoid: Reviews Platform_, yet. Click **Install Reviews app**, then **Install app**, and approve the app in Shopify. On a store that's already connected to your workspace, the app joins the same workspace. Then turn on the app embed.

A vintage Shopify theme has no app embeds. Copy the script under _Install with code_ in the dialog instead, and paste it into `theme.liquid`, right before the closing `</head>` tag.

**General implementation**

On other platforms and headless storefronts, paste the script from _Install with code_ into your site's code, right before the closing `</head>` tag on every page. For the steps, see [Add the Cevoid script](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md#add-the-cevoid-script).

## Embed a review widget

Embed a review widget with a Shopify theme block, or with code on any other site.

**Shopify**

On Shopify, add review widgets with the blocks of the Cevoid: Reviews Platform app. The blocks need an Online Store 2.0 theme.

> [!NOTE]
> Vintage themes have no app blocks, and headless Shopify stores don't use the theme editor. Use the general implementation instructions instead.

| Block | Template | Use it for |
| --- | --- | --- |
| **Product reviews** | Product | Product page widgets: review lists, rating summaries, AI summaries, and question summaries |
| **Product rating** | Product, in the main product section by the price | **Dynamic Product Rating** widgets, and the rating for [Google Rich Snippets](https://docs.cevoid.com/reviews/showcase/google-rich-snippets.md) |
| **Collection reviews** | Collection | **Dynamic Collection Product Reviews** |
| **Category reviews** | Product | **Dynamic Category Product Reviews**, with the category from the product's type |
| **Brand reviews** | Product | **Dynamic Brand Product Reviews**, with the brand from the product's vendor |
| **Review widget** | Any template, and section groups such as the header and footer | Curated and company widgets |
| **Cevoid Reviews** | Every page, as an app embed | The Cevoid script, with no widget |

Each widget block has two settings: _Widget ID_ and _Show test data_. On the **Product rating** block, _Widget ID (optional)_ can stay empty: the block then shows the rating stored in Shopify's product rating metafields.

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) and open the widget
2. Click **Embed widget**. If _Embed with Shopify_ shows _App required_, click **Install Reviews app** first.
3. Click **Embed to store**. Cevoid copies the widget ID and opens the Shopify theme editor in a new tab.
4. Open the page where the widget belongs in the Shopify theme editor. Dynamic widgets open on their template, with the block already added.
5. Click **Add block** and search for `Cevoid`, if the editor didn't add the block
6. Select the block for the widget, such as **Review widget** for a curated widget
7. Paste the widget ID in _Widget ID_
8. Click **Save**

Each block of the Reviews app loads the Cevoid script on the page it's on. Review request links open the review form on your start page, so also turn on the app embed, which loads the script on every page: see [Add the Cevoid script](https://docs.cevoid.com/reviews/showcase/embed-review-widgets#add-the-cevoid-script).

In the theme editor, a block that doesn't match its widget shows a notice instead of the widget, such as _This widget needs a product. Use the Product reviews block._ or _This widget takes no page context. Use the Review widget block._ A block with no ID shows _Paste a Cevoid widget ID in the block settings to show reviews here._ Shoppers see nothing in either case.

**General implementation**

> [!NOTE]
> This setup needs access to your site's code. If you don't edit it yourself, share these steps with your developer.

Embed review widgets on any website with one `cevoid-reviews` element per placement. This also works on Shopify stores with a vintage theme or a headless storefront. The page needs the Cevoid script first: see [Add the Cevoid script](https://docs.cevoid.com/integrations/ecommerce/general-implementation.md#add-the-cevoid-script).

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) and open the widget
2. Click **Embed widget**
3. Copy the element under _Add the widget_
4. Paste the element where the widget should appear
5. Publish the changes to your site

The element names the widget, and for a dynamic widget, the page context it needs:

```html
<cevoid-reviews data-widget="w_…" data-product="auto"></cevoid-reviews>
```

| Attribute | Value |
| --- | --- |
| `data-widget` | Required. The widget's ID |
| `data-product`, `data-collection`, `data-category`, or `data-brand` | Dynamic widgets only: the one that matches the widget, set to `auto` or an explicit value. Curated and company widgets take none |
| `data-mock` | `true` shows sample reviews instead of yours. See [Show sample reviews on your store](https://docs.cevoid.com/reviews/showcase/embed-review-widgets#show-sample-reviews-on-your-store) |
| `data-publishable-key` | Your publishable key, only when the script tag can't carry it |

`auto` reads the page's URL. A product matches its exact product URL, or else its handle, the last part of the path. A collection comes from the URL, and a category or brand from the URL or from the product on the page. For a product, an explicit value can be a Cevoid product or variant ID (`prd_…`, `var_…`), your platform's product or variant ID, a SKU, a GTIN, or the product's full URL.

**Star ratings on product cards:** To show each product's rating on a collection page, add a **Dynamic Product Rating** widget to every product card, with `data-product` set to that card's product. Each card loads its own rating. On Shopify, the **Product rating** block only works on product pages, so this needs code there too.

**Pages that change without a reload:** The Cevoid script also loads review widgets added to the page later, such as after a route change in a single-page application. A product review widget shows the reviews of the whole product, from all its variants, so a variant switch needs no refresh. To show another product's reviews without a reload, replace the `cevoid-reviews` element with a new one that has the same `data-widget` and the new `data-product`. Changing `data-product` on an element that's already on the page doesn't update it.

```javascript
// When the page shows another product without a reload
const current = document.querySelector('cevoid-reviews')
const next = document.createElement('cevoid-reviews')
next.dataset.widget = current.dataset.widget
next.dataset.product = newProductId
current.replaceWith(next)
```

**Headless storefronts:** The script and element work the same way. To render reviews and ratings on your own server instead, use Cevoid's Storefront API with your publishable key.

## Check the Cevoid script

_Embed script status_ checks whether the Cevoid script is on the storefront of each of your markets. Cevoid runs the check about every 6 hours, and when you click **Check status**. When a market isn't _Installed_, **Script status** and **Embed widget** on [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) show a warning.

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) and click **Script status**
2. Click **Check status** under _Embed script status_
3. Hover over a market's status to see the reason, such as _The Cevoid app embed is switched off in your Shopify theme._

| Status | What it means |
| --- | --- |
| _Installed_ | The script is on the storefront, with your workspace's key |
| _Missing_ | Cevoid found no script, or the browser couldn't load it. On Shopify, the app embed may be off |
| _Misconfigured_ | The script has no workspace key or another workspace's key, or the market has no valid web address |
| _Unreachable_ | The storefront didn't answer |
| _Can't check_ | The storefront is password protected, so Cevoid can't open it. On Shopify, save the storefront password: see [Check a password-protected storefront](https://docs.cevoid.com/reviews/showcase/embed-review-widgets#check-a-password-protected-storefront) |
| _Unknown_ | The check couldn't be completed |
| _Not checked_ | The market hasn't been checked yet |

### Check a password-protected storefront

A Shopify store that isn't open to visitors yet, such as a development store, answers with a password page, so Cevoid can't check its script. Save the storefront password, and Cevoid uses it to open the store.

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets) and click **Script status**
2. Click **Add storefront password** in the alert _Your storefront seems to be password protected_
3. Enter the password visitors use to open your store in _Password_. Shopify shows it under **Online Store** → **Preferences**.
4. Click **Save password**. Cevoid checks the script again.

To change or remove the password later, open the store in [Settings → Integrations → Shopify](https://app.cevoid.com/settings/integrations/shopify) and click **Change storefront password** under _General_. If the password stops working, the alert comes back as _Your storefront password no longer works_.

You can also save the password from [Settings → BrandKit](https://app.cevoid.com/settings/brandkit): click **Add storefront password** in the alert there, or fill in _Store password protected?_ when you import your BrandKit. It's the same password, and BrandKit imports use it too.

## Check that a widget is live

A review widget shows _Live_ on its card when it loaded on your storefront in the last 10 days, and _Not live_ otherwise. Loads in Cevoid's widget editor don't count.

1. Navigate to [Reviews → On-site widgets](https://app.cevoid.com/reviews/on-site-widgets)
2. Hover over _Live_ or _Not live_ on the widget's card. The page where the widget last loaded shows, or _Widget has not been loaded yet_.
3. Optional: Click the badge to open that page

## Show sample reviews on your store

Test data fills a review widget with sample reviews from a demo store, Void & Oak, instead of your own, so you can style it on your store before you have reviews. The widget keeps its own settings, styling, and text.

- **Shopify:** Enable _Show test data_ in the block's settings in the theme editor
- **Code:** Add `data-mock="true"` to the element

Shoppers see the sample reviews too, under the line _Sample reviews from Void & Oak_. Sample reviews add no rich snippet to the page, and reports on them aren't sent to your team. Turn test data off before you go live.

## Open reviews from a link

A link to any page of your store that loads the Cevoid script can open reviews in a popup, with no widget on the page. Add `?cevoid.widget=reviews.all-reviews` to the page's URL to open the _All reviews_ popup:

- **On a product page:** The popup shows the product's reviews
- **On any page:** Add `&cevoid.product=` and a product ID to show that product's reviews, or `&cevoid.id=` and a widget ID to show that widget's reviews
- **On a page with no product:** Without `cevoid.product` or `cevoid.id`, the popup opens with no reviews, on _No reviews yet_

```text
https://yourstore.com/?cevoid.widget=reviews.all-reviews&cevoid.id=w_…
```

The links in Cevoid's review emails work the same way. They open the review form, or the reviewed review with your reply, on your store.

## Troubleshooting

### Why doesn't a widget show on my store?

- **The script isn't on the page:** Check the [Cevoid script](https://docs.cevoid.com/reviews/showcase/embed-review-widgets#check-the-cevoid-script)
- **The block doesn't fit the widget:** The theme editor shows a notice, such as _This widget needs a product. Use the Product reviews block._ Use the block for the widget's template.
- **The block has no widget ID:** The theme editor shows _Paste a Cevoid widget ID in the block settings to show reviews here._
- **The page context doesn't resolve:** With code, `auto` finds nothing on a page whose URL doesn't match a product, collection, category, or brand. Set an explicit value.
- **The widget waits for ratings:** With _When empty_ on **Hidden**, a widget shows once it has the number of ratings you set. See [Review widget settings](https://docs.cevoid.com/reviews/showcase/review-widget-settings.md).
- **The product is on your review blocklist:** Product page widgets show nothing on a blocklisted product with no ratings
- **The widget was deleted:** Its block or element stays on the page, but shows nothing

### Why don't my changes show on my store?

Saving a widget updates your store right away. Changes to your [moderation settings](https://docs.cevoid.com/reviews/manage/moderation.md), such as helpful votes and reports, and to translations, can take up to 5 minutes to reach your store.

## Related articles

- [Review widgets](https://docs.cevoid.com/reviews/showcase/review-widgets.md)
- [Reviews setup checklist](https://docs.cevoid.com/reviews/setup/setup-checklist.md)
- [Google Rich Snippets](https://docs.cevoid.com/reviews/showcase/google-rich-snippets.md)
- [Shopify](https://docs.cevoid.com/integrations/ecommerce/shopify.md)

---

Canonical: https://docs.cevoid.com/reviews/showcase/embed-review-widgets